View mode: basic / threaded / horizontal-split · Log in · Help
June 05, 2004
Doxygen filter fix
I've fixed a few more bugs in dfilter for Doxygen. Now available here:

http://www.hazardarea.com/dfilter.zip

I have written this before, but buried relatively deep in another 
thread, so I'll try again:

I really think this should be a project on dsource.org. Are there any 
volunteers for the job of project maintainer? To be honest, I don't want 
to maintain the project myself because my free time is rather limited 
lately.

Any takers?

Hauke
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
"Hauke Duden" <H.NS.Duden@gmx.net> wrote in message
news:c9ti1f$2vft$1@digitaldaemon.com...
> I've fixed a few more bugs in dfilter for Doxygen. Now available here:
>
> http://www.hazardarea.com/dfilter.zip
>
> I have written this before, but buried relatively deep in another
> thread, so I'll try again:
>
> I really think this should be a project on dsource.org.

Agreed.

> Are there any
> volunteers for the job of project maintainer? To be honest, I don't want
> to maintain the project myself because my free time is rather limited
> lately.

I'm in the same boat.

If there were a couple of regular maintainers, I'd be happy to lend an occasional
hand, but it'd be very occasional.

btw, what do we feel about adopting Doxygen as a current-best-plan working
standard for Phobos documentation? In other words, new Phobos additions should be
doxygenated. It's pretty easy to do, and the syntax is sufficiently general that
we could write filters to adapt the code, or even automate the rewriting, should
we change to a new, better, standard documenter in the future.
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
Matthew wrote:

>btw, what do we feel about adopting Doxygen as a current-best-plan working
>standard for Phobos documentation? In other words, new Phobos additions should be
>doxygenated. It's pretty easy to do, and the syntax is sufficiently general that
>we could write filters to adapt the code, or even automate the rewriting, should
>we change to a new, better, standard documenter in the future.
>  
>
Most certainly a good idea.

-- 
-Anderson: http://badmama.com.au/~anderson/
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
Matthew wrote:
> btw, what do we feel about adopting Doxygen as a current-best-plan working
> standard for Phobos documentation? In other words, new Phobos additions should be
> doxygenated. It's pretty easy to do, and the syntax is sufficiently general that
> we could write filters to adapt the code, or even automate the rewriting, should
> we change to a new, better, standard documenter in the future.

I think it's a good idea. I've been using Doxygen for a long time with 
C++ and it is simply one of the very best tools out there.

And it already works quite well with D. My unichar and utype modules are 
documented with Doxygen and the result is flawless.

There are still some ugly things like general templates being documented 
as template classes and the like (mostly because none of the other 
languages has a comparable feature). But if D really takes off it will 
only be a matter of time until the proper support is added.

Hauke
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
In article <c9unbd$1fpo$1@digitaldaemon.com>, J Anderson says...

Forgive me for this question. I'm not trying to be be devil's advocate here, but
I'm genuinely ignorant about some things, and this is one of them.

What is the advantage of embedded comments which convert to documentation,
compared with, say, embedded HTML documentation like Walter suggests over at
http://www.digitalmars.com/d/html.html. I would have thought that embedded HTML
was *the* way to go, no? It's one cool thing the D can do that other languages
can't.

Arcane Jill
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
Arcane Jill wrote:

> In article <c9unbd$1fpo$1@digitaldaemon.com>, J Anderson says...
> 
> Forgive me for this question. I'm not trying to be be devil's advocate here, but
> I'm genuinely ignorant about some things, and this is one of them.
> 
> What is the advantage of embedded comments which convert to documentation,
> compared with, say, embedded HTML documentation like Walter suggests over at
> http://www.digitalmars.com/d/html.html. I would have thought that embedded HTML
> was *the* way to go, no? It's one cool thing the D can do that other languages
> can't.

Doxygen does many things that you'd have to do manually in pure HTML. 
For example, it automatically provides short overviews with one-sentence 
descriptions, it creates class hierarchy diagrams, it can automatically 
create links from entity names, it can link in external documentation, 
produce todo lists, provide alphabetical entity lists, automatically 
generate Latex or XML versions and it even provides a search engine.

In other words, the tool just plain rocks ;)

And of course if a tool creates the documentation it is guaranteed that 
all of it will be consistent in structure.

Hauke
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
Hauke Duden wrote:

> Arcane Jill wrote:
>
>> In article <c9unbd$1fpo$1@digitaldaemon.com>, J Anderson says...
>>
>> Forgive me for this question. I'm not trying to be be devil's 
>> advocate here, but
>> I'm genuinely ignorant about some things, and this is one of them.
>>
>> What is the advantage of embedded comments which convert to 
>> documentation,
>> compared with, say, embedded HTML documentation like Walter suggests 
>> over at
>> http://www.digitalmars.com/d/html.html. I would have thought that 
>> embedded HTML
>> was *the* way to go, no? It's one cool thing the D can do that other 
>> languages
>> can't.
>
>
> Doxygen does many things that you'd have to do manually in pure HTML. 
> For example, it automatically provides short overviews with 
> one-sentence descriptions, it creates class hierarchy diagrams, it can 
> automatically create links from entity names, it can link in external 
> documentation, produce todo lists, provide alphabetical entity lists, 
> automatically generate Latex or XML versions and it even provides a 
> search engine.
>
> In other words, the tool just plain rocks ;)
>
> And of course if a tool creates the documentation it is guaranteed 
> that all of it will be consistent in structure.
>
> Hauke

Hauke Duden wrote:

-- 
-Anderson: http://badmama.com.au/~anderson/

> Arcane Jill wrote:
>
>> In article <c9unbd$1fpo$1@digitaldaemon.com>, J Anderson says...
>>
>> Forgive me for this question. I'm not trying to be be devil's 
>> advocate here, but
>> I'm genuinely ignorant about some things, and this is one of them.
>>
>> What is the advantage of embedded comments which convert to 
>> documentation,
>> compared with, say, embedded HTML documentation like Walter suggests 
>> over at
>> http://www.digitalmars.com/d/html.html. I would have thought that 
>> embedded HTML
>> was *the* way to go, no? It's one cool thing the D can do that other 
>> languages
>> can't.
>
>
> Doxygen does many things that you'd have to do manually in pure HTML. 
> For example, it automatically provides short overviews with 
> one-sentence descriptions, it creates class hierarchy diagrams, it can 
> automatically create links from entity names, it can link in external 
> documentation, produce todo lists, provide alphabetical entity lists, 
> automatically generate Latex or XML versions and it even provides a 
> search engine.
>
> In other words, the tool just plain rocks ;)
>
> And of course if a tool creates the documentation it is guaranteed 
> that all of it will be consistent in structure.
>
> Hauke

Right.  Also you don't need to provide the code with the source as you 
do with D's embedded html.  I'm not saying D's embedded html is a good 
comparison as they are just different beasts.

-- 
-Anderson: http://badmama.com.au/~anderson/
June 06, 2004
Embedding D in HTML (Re: Doxygen filter fix [...])
Arcane Jill wrote:
> In article <c9unbd$1fpo$1@digitaldaemon.com>, J Anderson says...
> 
> Forgive me for this question. I'm not trying to be be devil's advocate here, but
> I'm genuinely ignorant about some things, and this is one of them.
> 
> What is the advantage of embedded comments which convert to documentation,
> compared with, say, embedded HTML documentation like Walter suggests over at
> http://www.digitalmars.com/d/html.html. I would have thought that embedded HTML
> was *the* way to go, no? It's one cool thing the D can do that other languages
> can't.
> 
> Arcane Jill

I like the idea of embedding D in HTML, but I think it's better suited 
for tutorials than library documentation. Once the code is converted to 
HTML it's more difficult to edit. For example, the "<" symbol becomes 
"&lt;" and ">" becomes "&gt;".

I've found that embedding D in HTML works easiest when it's generated by 
a D2HTML program (such as how the dsource.org tutorial examples are 
created).

-- 
Justin (a/k/a jcc7)
http://jcc_7.tripod.com/d/
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
In article <c9utp3$1ob2$1@digitaldaemon.com>, Hauke Duden says...
>
>Doxygen does many things that you'd have to do manually in pure HTML. 
>For example, it automatically provides short overviews with one-sentence 
>descriptions, it creates class hierarchy diagrams, it can automatically 
>create links from entity names, it can link in external documentation, 
>produce todo lists, provide alphabetical entity lists, automatically 
>generate Latex or XML versions and it even provides a search engine.
>
>In other words, the tool just plain rocks ;)
>
>And of course if a tool creates the documentation it is guaranteed that 
>all of it will be consistent in structure.
>
>Hauke

Ok, I'm convinced. Can you point me in the direction of some
information/documentation/whatever? Once I've figured out how to use it, it
sounds like I ought to document my own stuff using this.

And if what you say is true, then, in line with the thread title, documenting
Phobos in this way might be really cool too. Did you say there was some problem
with documenting templates though?

I wonder if this sort of thing could be actually built into a language itself?
Something like:

>       uint myFunction(uint x)
>       doc
>       {
>           "This is a completely pointless function which you should";
>           "only ever need to call if you've had too much to drink";
>       }
>       in
>       {
>           assert(x > 5);
>       }
>       body
>       {
>           return (x == 7) ? 93 : x + 2;
>       }

..with documentation generated by the compiler at compile-time? Yeah, I know -
Walter's W-A-Y too busy to think about that. Still...

Arcane Jill
June 06, 2004
Re: Doxygen filter fix [Phobos documentation working standard?]
Arcane Jill wrote:
> In article <c9utp3$1ob2$1@digitaldaemon.com>, Hauke Duden says...
> 
>>Doxygen does many things that you'd have to do manually in pure HTML. 
>>For example, it automatically provides short overviews with one-sentence 
>>descriptions, it creates class hierarchy diagrams, it can automatically 
>>create links from entity names, it can link in external documentation, 
>>produce todo lists, provide alphabetical entity lists, automatically 
>>generate Latex or XML versions and it even provides a search engine.
>>
>>In other words, the tool just plain rocks ;)
>>
>>And of course if a tool creates the documentation it is guaranteed that 
>>all of it will be consistent in structure.
>>
>>Hauke
> 
> 
> Ok, I'm convinced. Can you point me in the direction of some
> information/documentation/whatever? Once I've figured out how to use it, it
> sounds like I ought to document my own stuff using this.

http://www.doxygen.org :)

has everything you'll need. Tutorials, reference docs, examples etc.

> And if what you say is true, then, in line with the thread title, documenting
> Phobos in this way might be really cool too. Did you say there was some problem
> with documenting templates though?

Yes, because Doxygen does not yet fully support D (there is some 
preliminary support but it is far from complete). However, there is a 
Doxygen filter that translates some D constructs into similar constructs 
found in C#, C++ or Java. With this filter the documentation is quite good.

But non-class templates are not (yet) supported by the other languages, 
so the filter translates them into C++-like template classes.

But doxygen is pretty easy to extend, so it is only a matter of time. 
And if any of the other languages get similar templates (Java 1.5 and C# 
2 both want to introduce templates but I'm not sure if those are only 
class templates) it will be trivial.


> I wonder if this sort of thing could be actually built into a language itself?
> Something like:
> 
> 
>>      uint myFunction(uint x)
>>      doc
>>      {
>>          "This is a completely pointless function which you should";
>>          "only ever need to call if you've had too much to drink";
>>      }
>>      in
>>      {
>>          assert(x > 5);
>>      }
>>      body
>>      {
>>          return (x == 7) ? 93 : x + 2;
>>      }
> 
> 
> ..with documentation generated by the compiler at compile-time? Yeah, I know -
> Walter's W-A-Y too busy to think about that. Still...

Naa. Good documentation tools are a LOT of work. Doxygen needed years to 
become what it is now and there are a multitude of failed projects in 
that area.

I think it's best to just use existing tools.

Hauke
Top | Discussion index | About this forum | D home