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

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

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/

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

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

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:

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

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/

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

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