www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Doxygen filter fix

reply Hauke Duden <H.NS.Duden gmx.net> writes:
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
Jun 05 2004
parent reply "Matthew" <matthew.hat stlsoft.dot.org> writes:
"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.
Jun 06 2004
next sibling parent reply J Anderson <REMOVEanderson badmama.com.au> writes:
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/
Jun 06 2004
parent reply Arcane Jill <Arcane_member pathlink.com> writes:
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
Jun 06 2004
next sibling parent reply Hauke Duden <H.NS.Duden gmx.net> writes:
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
Jun 06 2004
next sibling parent J Anderson <REMOVEanderson badmama.com.au> writes:
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/
Jun 06 2004
prev sibling parent reply Arcane Jill <Arcane_member pathlink.com> writes:
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
Jun 06 2004
parent Hauke Duden <H.NS.Duden gmx.net> writes:
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 


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. 

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
Jun 06 2004
prev sibling parent J C Calvarese <jcc7 cox.net> writes:
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/
Jun 06 2004
prev sibling parent Hauke Duden <H.NS.Duden gmx.net> writes:
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
Jun 06 2004