View mode: basic / threaded / horizontal-split · Log in · Help
May 04, 2005
Re: Preferred style of comments in source code.
> I see.  So I guess one could also build Harmonia on top of an OpenGL 
> surface as well, if need be?

Yes. There is only one Graphics object which handles all drawings
in Harmonia. If you will implement its methods for OpenGL it will work on 
OpenGL:

Graphics class is here (undocumented so far):
http://terrainformatica.com/screenshots/graphics.d
There are two more files in gx package
http://terrainformatica.com/screenshots/geometry.d
http://terrainformatica.com/screenshots/images.d
but they are directly unrelated to the rendering process.

>
> 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?

As I've mentioned before it is already available on our SVN server.
No anonymous access so far though.

>
> Harmonia is really quite pretty!
>

Thanks.
May 04, 2005
Re: Preferred style of comments in source code.
On Wed, 4 May 2005 14:54:33 -0700, Andrew Fedoniouk wrote:

> 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");"
> .....

LOL ... Yes that is a bit obtuse. That was a 'special' case in which I
wanted to bold certain delimiter characters, and I chose to use '<' which
can get Browsers confused. I could have simply coded it as ...

> They take the forms ...
> /code
>       pragma( name );
>       pragma( name, option [, option] );
> /endcode


> 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? :(

That is exactly why docs and code should be in the same file. The better
development strategy is to write up the documentation then implement what
you documented. If they are physically close to each other, it becomes easy
to tweak either the docs or code as required, and keep them in sync. When
they are in different files, the human tendency is to write code then, if
time permits, update the docs.

-- 
Derek Parnell
Melbourne, Australia
http://www.dsource.org/projects/build/ v2.06 released 04/May/2005
http://www.prowiki.org/wiki4d/wiki.cgi?FrontPage
5/05/2005 9:02:12 AM
May 04, 2005
Re: Preferred style of comments in source code.
On Wed, 4 May 2005 14:47:24 -0700, Andrew Fedoniouk wrote:

> Thanks for the link.

>> http://www.naturaldocs.org/documenting.html

> Indeed looks nice. It is a plus.
> No D support. It is a minus. Striking out :)


Wow! This is *so* close to what I'm doing that I might just be able to
implement a lot of this in my MakeDoc utility.

-- 
Derek
Melbourne, Australia
5/05/2005 9:03:56 AM
May 04, 2005
Re: Preferred style of comments in source code.
Derek, and how far this *so* is close to it?

I have some time today to start writing docs.... :)

Andrew


"Derek Parnell" <derek@psych.ward> wrote in message 
news:owbprp404kz0.125ty6odtthz9.dlg@40tude.net...
> On Wed, 4 May 2005 14:47:24 -0700, Andrew Fedoniouk wrote:
>
>> Thanks for the link.
>
>>> http://www.naturaldocs.org/documenting.html
>
>> Indeed looks nice. It is a plus.
>> No D support. It is a minus. Striking out :)
>
>
> Wow! This is *so* close to what I'm doing that I might just be able to
> implement a lot of this in my MakeDoc utility.
>
> -- 
> Derek
> Melbourne, Australia
> 5/05/2005 9:03:56 AM
May 04, 2005
Re: Preferred style of comments in source code.
On Wed, 4 May 2005 16:22:01 -0700, Andrew Fedoniouk wrote:

> Derek, and how far this *so* is close to it?

Hard to quantify. I need some time to inspect it a bit more. The thing that
immediately causes me to hesitate is that it seems to want to know about
the syntax of the language the program is coded in. I am trying to avoid
that. There maybe a compromise though.

> I have some time today to start writing docs.... :)

Then start writing! I'd stick to plain text until you decide on which
'markup' style to use. I'm still a few days away from finishing my port of
MakeDoc to D, and when that's completed I can look at incorporating some of
the ideas from the 'Natural' guys.

-- 
Derek
Melbourne, Australia
5/05/2005 9:27:49 AM
May 05, 2005
Re: Preferred style of comments in source code.
On Wed, 04 May 2005 15:57:42 -0700, Andrew Fedoniouk wrote:

>> I see.  So I guess one could also build Harmonia on top of an OpenGL 
>> surface as well, if need be?
> 
> Yes. There is only one Graphics object which handles all drawings
> in Harmonia. If you will implement its methods for OpenGL it will work on 
> OpenGL:
> 
> Graphics class is here (undocumented so far):
> http://terrainformatica.com/screenshots/graphics.d
> There are two more files in gx package
> http://terrainformatica.com/screenshots/geometry.d
> http://terrainformatica.com/screenshots/images.d
> but they are directly unrelated to the rendering process.

Great, thanks.

>>
>> 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?
> 
> As I've mentioned before it is already available on our SVN server.
> No anonymous access so far though.

Ah... you probably have mentioned it before. I'll have a look at your svn
server then. 

-JJR
May 05, 2005
Re: Preferred style of comments in source code.
> Then start writing! I'd stick to plain text until....

Plain text!? No way!

I've recalled that I have nice html wysiwyg editor :))
The fastest editor in the block, btw, :-P
Here is the first bird:
http://www.terrainformatica.com/harmonia/map.htm

(btw. I don't know how people are doing html tables without wysiwyg...)

Andrew.



"Derek Parnell" <derek@psych.ward> wrote in message 
news:14bv0u5bbdzvy$.1njq6ruyaxj9n$.dlg@40tude.net...
> On Wed, 4 May 2005 16:22:01 -0700, Andrew Fedoniouk wrote:
>
>> Derek, and how far this *so* is close to it?
>
> Hard to quantify. I need some time to inspect it a bit more. The thing 
> that
> immediately causes me to hesitate is that it seems to want to know about
> the syntax of the language the program is coded in. I am trying to avoid
> that. There maybe a compromise though.
>
>> I have some time today to start writing docs.... :)
>
> Then start writing! I'd stick to plain text until you decide on which
> 'markup' style to use. I'm still a few days away from finishing my port of
> MakeDoc to D, and when that's completed I can look at incorporating some 
> of
> the ideas from the 'Natural' guys.
>
> -- 
> Derek
> Melbourne, Australia
> 5/05/2005 9:27:49 AM
May 05, 2005
Re: Preferred style of comments in source code.
On Wed, 4 May 2005 23:25:55 -0700, Andrew Fedoniouk wrote:

>> Then start writing! I'd stick to plain text until....
> 
> Plain text!? No way!
> 
> I've recalled that I have nice html wysiwyg editor :))
> The fastest editor in the block, btw, :-P

LOL... I looked at BlockNote site just now and thought, hmmm... I've seen
this style of GUI before ... then I saw the " Andrew Fedoniouk. Author of
the BlockNote."

Nice product.

> Here is the first bird:
> http://www.terrainformatica.com/harmonia/map.htm

I think I know which GUI engine I'll be porting my windowing library to ;-)

> (btw. I don't know how people are doing html tables without wysiwyg...)

Huh?  What's a html table ;-)

-- 
Derek Parnell
Melbourne, Australia
http://www.dsource.org/projects/build/ v2.06 released 04/May/2005
http://www.prowiki.org/wiki4d/wiki.cgi?FrontPage
5/05/2005 4:46:06 PM
May 05, 2005
Re: Preferred style of comments in source code.
Yuck.  I don't know how people can stand to use a wysiwywyg editor.

-[Unknown]


> (btw. I don't know how people are doing html tables without wysiwyg...)
May 05, 2005
Re: Preferred style of comments in source code.
Andrew Fedoniouk wrote:

> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....

Consensus ? You must be new around here :-)


Seriously, I put up some minor comment examples of a
JavaDoc/Doxygen based inline documentation style, at:

http://www.prowiki.org/wiki4d/wiki.cgi?DocComments/DStyle

I've used it for C/C++ projects (and for a lot of Java...),
and it has worked out good. Minimal "boilerplate" to write.


Doxygen still has a few issues with any "complicated" D constructs,
but it's working OK for the simple stuff - especially with dfilter.

See http://www.prowiki.org/wiki4d/wiki.cgi?DoxygenIssues

Dmitri is accepting bug reports for Doxygen and the D language,
especially if they come with patches and source code to fix them...

--anders
1 2 3
Top | Discussion index | About this forum | D home