May 04, 2005
What was last consensus, gentlemen?

Java, doxygen flavour, C# or what?

Phobos has samples of all styles....

Personally I don't like them all because they are mostly non readable in
source code,
but, yes, they produce  more or less good results in generated docs.
BTW: Do you know examples of useful generated docs?  (url will be
appreciated)

I am going to use something extremely simple like:

/**  show - Shows tooltip window
 - tt - ITooltip, reference to the implementation of ITooltip
   interface - source of tooltip text.
 - screenPos - point, screen relative coordinates of the
   origin of the tooltip window.
 = true - if window was shown, false - otherwise
 **/
bool show(ITooltip tt, point screenPos) { ... }

this is human readable (I guess ) and could be used as a source of generated doc.

Any ideas?

==============================================
Seems like D *will* have a declarative UI (whatever it means) ahead of time:
I've almost finished with "springs" (vertical and horizontal)
See: http://terrainformatica.com/screenshots/harmonia1.png
And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip

Andrew.


May 04, 2005
Andrew Fedoniouk wrote:
> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....
> 
> Personally I don't like them all because they are mostly non readable in source code,
> but, yes, they produce  more or less good results in generated docs.
> BTW: Do you know examples of useful generated docs?  (url will be appreciated)
> 
> I am going to use something extremely simple like:
> 
> /**  show - Shows tooltip window
>  - tt - ITooltip, reference to the implementation of ITooltip
>    interface - source of tooltip text.
>  - screenPos - point, screen relative coordinates of the
>    origin of the tooltip window.
>  = true - if window was shown, false - otherwise
>  **/
> bool show(ITooltip tt, point screenPos) { ... }
> 
> this is human readable (I guess ) and could be used as a source of generated doc.
> 
> Any ideas?
> 
> ==============================================
> Seems like D *will* have a declarative UI (whatever it means) ahead of time:
> I've almost finished with "springs" (vertical and horizontal)
> See: http://terrainformatica.com/screenshots/harmonia1.png
> And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip
> 
> Andrew. 
> 
> 

I might have missed this in the forums:  is harmonia available on Linux as well?

-JJR
May 04, 2005
Did you see Charlie's recent post about natural docs (www.naturaldocs.org) ? Here's a sample on how to document: http://www.naturaldocs.org/documenting.html

Seems pretty readable, doesn't it?
The downside is, there's no current support for D...


Pablo

"Andrew Fedoniouk" <news@terrainformatica.com> wrote in message news:d5bc5i$2pd6$1@digitaldaemon.com...
> What was last consensus, gentlemen?
>
> Java, doxygen flavour, C# or what?
>
> Phobos has samples of all styles....
>
> Personally I don't like them all because they are mostly non readable in
> source code,
> but, yes, they produce  more or less good results in generated docs.
> BTW: Do you know examples of useful generated docs?  (url will be
> appreciated)
>
> I am going to use something extremely simple like:
>
> /**  show - Shows tooltip window
> - tt - ITooltip, reference to the implementation of ITooltip
>   interface - source of tooltip text.
> - screenPos - point, screen relative coordinates of the
>   origin of the tooltip window.
> = true - if window was shown, false - otherwise
> **/
> bool show(ITooltip tt, point screenPos) { ... }
>
> this is human readable (I guess ) and could be used as a source of generated doc.
>
> Any ideas?
>
> ==============================================
> Seems like D *will* have a declarative UI (whatever it means) ahead of
> time:
> I've almost finished with "springs" (vertical and horizontal)
> See: http://terrainformatica.com/screenshots/harmonia1.png
> And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip
>
> Andrew.
> 


May 04, 2005
On Wed, 4 May 2005 13:43:29 -0700, Andrew Fedoniouk wrote:

> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....
> 
> Personally I don't like them all because they are mostly non readable in
> source code,
> but, yes, they produce  more or less good results in generated docs.
> BTW: Do you know examples of useful generated docs?  (url will be
> appreciated)
> 
> I am going to use something extremely simple like:
> 
> /**  show - Shows tooltip window
>  - tt - ITooltip, reference to the implementation of ITooltip
>    interface - source of tooltip text.
>  - screenPos - point, screen relative coordinates of the
>    origin of the tooltip window.
>  = true - if window was shown, false - otherwise
>  **/
> bool show(ITooltip tt, point screenPos) { ... }
> 
> this is human readable (I guess ) and could be used as a source of generated doc.
> 
> Any ideas?

I've used a system of embedding documentation in source code for a few years now that is based on a simple markup language. The documentation is extracted from the source code and a set of HTML files is generated. You can see the source code of 'build.d' from the download for a bigger example but here is a smaller example ...

/* ============= The User Manual ======================================
__ /topic Introduction
__ /info
__ This is a utility to build an application using the D programming
__ language.
__ It does this by examining the source file supplied on the command line
__ to work out its dependant files, and then determines which need to be
__  compiled and which need to be linked to create the executable.
__
__ Alternatively, it can be used to create a Library file rather than an
__  executable.
__
__ The aim of the utility is to help remove the need for /i make files
__  or similar devices.

__ /topic Pragma
__ /info
__ The /b build utility supports the use of various pragma statements.
__ A pragma is a special statement embedded in the source code that
__  provides information to tools reading the source code.
__
__ They take the forms ...
__ /code
__       /b"pragma(" ~<name~> /b");"
__       /b"pragma(" ~<name~> /b"," ~<option~> [ /b","~<option~>] /b");"
__ /endcode
__
__ If the D compiler doesn't recognise the pragma, it will fail. So to
__  'hide' them from the compiler, you need to wrap them in a /b version
__  block. All the pragmas used by this utility need to be enclosed in
__  a /i build version.
__
__ Example:
__ /code
__       version(build) { pragma(nolink); }
__ /endcode

*/

This example doesn't show many of the neat features of the SML, but the advantages for me is that it is simple to use, simple to remember, removes the concern about layout, and you can write the documentation near the code it relates to and it all gets pulled together during the generation process. The generated HTML is simple and not distracting.

  http://svn.dsource.org/svn/projects/build/trunk/Docs/index.htm

The generator is a Euphoria program, but I'm currently porting it to D. And BTW, that is a very simple thing to do and it has already found a couple of old bugs.

-- 
Derek Parnell
Melbourne, Australia
http://www.dsource.org/projects/build v2.06 is now available. 04/May/2005
5/05/2005 7:05:01 AM
May 04, 2005
On Wed, 4 May 2005 13:43:29 -0700, Andrew Fedoniouk wrote:


Another example of the generated docs using the system I mentioned can be found at ...

  http://www.users.bigpond.com/ddparnell/Euphoria/Docs/index.htm

This is the documentation for the Windows toolkit that I will be porting to D one day.

-- 
Derek Parnell
Melbourne, Australia
http://www.dsource.org/projects/build v2.06 is now available. 04/May/2005
5/05/2005 7:12:56 AM
May 04, 2005
>
> I might have missed this in the forums:  is harmonia available on Linux as well?
>

Not yet but it will be available on Linux too if somebody will
agree to help me in this. My Linux GUI programming experience is
more theoretical than practical.
As Harmonia is not using OS input widgets (only top level window frames)
then it is possible to build Harmonia/Linux in the window manager agnostic
fashion - directly on top of XWindow. (My guess)
Moreover Harmonia by itself can be used as a window manager or more
precise - window manager could be built using Harmonia.

Andrew.






May 04, 2005
Thanks for the link.
Indeed looks nice. It is a plus.
No D support. It is a minus. Striking out :)

Andrew.


"Pablo Aguilar" <paguilarg@hotmail.com> wrote in message news:d5bd9s$2q9v$1@digitaldaemon.com...
> Did you see Charlie's recent post about natural docs (www.naturaldocs.org)
> ?
> Here's a sample on how to document:
> http://www.naturaldocs.org/documenting.html
>
> Seems pretty readable, doesn't it?
> The downside is, there's no current support for D...
>
>
> Pablo
>
> "Andrew Fedoniouk" <news@terrainformatica.com> wrote in message news:d5bc5i$2pd6$1@digitaldaemon.com...
>> What was last consensus, gentlemen?
>>
>> Java, doxygen flavour, C# or what?
>>
>> Phobos has samples of all styles....
>>
>> Personally I don't like them all because they are mostly non readable in
>> source code,
>> but, yes, they produce  more or less good results in generated docs.
>> BTW: Do you know examples of useful generated docs?  (url will be
>> appreciated)
>>
>> I am going to use something extremely simple like:
>>
>> /**  show - Shows tooltip window
>> - tt - ITooltip, reference to the implementation of ITooltip
>>   interface - source of tooltip text.
>> - screenPos - point, screen relative coordinates of the
>>   origin of the tooltip window.
>> = true - if window was shown, false - otherwise
>> **/
>> bool show(ITooltip tt, point screenPos) { ... }
>>
>> this is human readable (I guess ) and could be used as a source of generated doc.
>>
>> Any ideas?
>>
>> ==============================================
>> Seems like D *will* have a declarative UI (whatever it means) ahead of
>> time:
>> I've almost finished with "springs" (vertical and horizontal)
>> See: http://terrainformatica.com/screenshots/harmonia1.png
>> And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip
>>
>> Andrew.
>>
>
> 


May 04, 2005
Thanks a lot, Derek,

Yes it close but the style I would like to avoid is:

__ They take the forms ...
__ /code
__       /b"pragma(" ~<name~> /b");"
__       /b"pragma(" ~<name~> /b"," ~<option~> [ /b","~<option~>] /b");"
__ /endcode

For me (probably only for me) it is hard to read something like this:
    /b"pragma(" ~<name~> /b");"
.....

The more I am looking on this the more coming to the conclusion
that documentation and source code should be separated.
But where to get time for such docs? :(

Andrew.


"Derek Parnell" <derek@psych.ward> wrote in message news:6xes2p79xu69$.16cxjkqk2ffic$.dlg@40tude.net...
> On Wed, 4 May 2005 13:43:29 -0700, Andrew Fedoniouk wrote:
>
>> What was last consensus, gentlemen?
>>
>> Java, doxygen flavour, C# or what?
>>
>> Phobos has samples of all styles....
>>
>> Personally I don't like them all because they are mostly non readable in
>> source code,
>> but, yes, they produce  more or less good results in generated docs.
>> BTW: Do you know examples of useful generated docs?  (url will be
>> appreciated)
>>
>> I am going to use something extremely simple like:
>>
>> /**  show - Shows tooltip window
>>  - tt - ITooltip, reference to the implementation of ITooltip
>>    interface - source of tooltip text.
>>  - screenPos - point, screen relative coordinates of the
>>    origin of the tooltip window.
>>  = true - if window was shown, false - otherwise
>>  **/
>> bool show(ITooltip tt, point screenPos) { ... }
>>
>> this is human readable (I guess ) and could be used as a source of
>> generated
>> doc.
>>
>> Any ideas?
>
> I've used a system of embedding documentation in source code for a few
> years now that is based on a simple markup language. The documentation is
> extracted from the source code and a set of HTML files is generated. You
> can see the source code of 'build.d' from the download for a bigger
> example
> but here is a smaller example ...
>
> /* ============= The User Manual ======================================
> __ /topic Introduction
> __ /info
> __ This is a utility to build an application using the D programming
> __ language.
> __ It does this by examining the source file supplied on the command line
> __ to work out its dependant files, and then determines which need to be
> __  compiled and which need to be linked to create the executable.
> __
> __ Alternatively, it can be used to create a Library file rather than an
> __  executable.
> __
> __ The aim of the utility is to help remove the need for /i make files
> __  or similar devices.
>
> __ /topic Pragma
> __ /info
> __ The /b build utility supports the use of various pragma statements.
> __ A pragma is a special statement embedded in the source code that
> __  provides information to tools reading the source code.
> __
> __ They take the forms ...
> __ /code
> __       /b"pragma(" ~<name~> /b");"
> __       /b"pragma(" ~<name~> /b"," ~<option~> [ /b","~<option~>] /b");"
> __ /endcode
> __
> __ If the D compiler doesn't recognise the pragma, it will fail. So to
> __  'hide' them from the compiler, you need to wrap them in a /b version
> __  block. All the pragmas used by this utility need to be enclosed in
> __  a /i build version.
> __
> __ Example:
> __ /code
> __       version(build) { pragma(nolink); }
> __ /endcode
>
> */
>
> This example doesn't show many of the neat features of the SML, but the
> advantages for me is that it is simple to use, simple to remember, removes
> the concern about layout, and you can write the documentation near the
> code
> it relates to and it all gets pulled together during the generation
> process. The generated HTML is simple and not distracting.
>
>  http://svn.dsource.org/svn/projects/build/trunk/Docs/index.htm
>
> The generator is a Euphoria program, but I'm currently porting it to D.
> And
> BTW, that is a very simple thing to do and it has already found a couple
> of
> old bugs.
>
> -- 
> Derek Parnell
> Melbourne, Australia
> http://www.dsource.org/projects/build v2.06 is now available. 04/May/2005
> 5/05/2005 7:05:01 AM


May 04, 2005
Andrew Fedoniouk wrote:
> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....
> 
> Personally I don't like them all ...

I really don't care what type of documentation is used, but it seems like there should be a standard. And it seems like that standard should be something like the D Style Guide, authored and maintained by Digital Mars. (Though I don't think many people actually pay much attention to the D style guide, preferring instead to stick with their old code formatting & variable naming habits from c++, java, perl, vb, or whatever.)

--Benji
May 04, 2005
Andrew Fedoniouk wrote:
>>I might have missed this in the forums:  is harmonia available on Linux as well?
>>
> 
> 
> Not yet but it will be available on Linux too if somebody will
> agree to help me in this. My Linux GUI programming experience is
> more theoretical than practical.
> As Harmonia is not using OS input widgets (only top level window frames)
> then it is possible to build Harmonia/Linux in the window manager agnostic
> fashion - directly on top of XWindow. (My guess)
> Moreover Harmonia by itself can be used as a window manager or more
> precise - window manager could be built using Harmonia.
> 
> Andrew.
> 

I see.  So I guess one could also build Harmonia on top of an OpenGL surface as well, if need be?

My XWindow programming skills are practically nil, but I wouldn't mind fooling around with some Linux GUI integration; I've basically only mildly familiar with working with GTK and OpenGL on both platforms; I realize GTK has no use here.  Is Harmonia going to be put on dsource at any time?

Thanks.  Harmonia is really quite pretty!

-JJR
« First   ‹ Prev
1 2 3
Top | Discussion index | About this forum | D home