Documentation Generation

[Adrian Ratnapala <raka@gonzo>]

Hello.  

I thought I would resurect that nice disussion we were having before on this
topic.

I have recently tried out two options:  kdoc and docxx.  Both of these
tools can produce LaTeX and HTML output.  (But I had to hack kdoc to the the
LaTeX backend to work).

Here is a pro-cons list of these too.  What other tools can people suggest?
I remember someone was raving about how good some particular tool was,
but I can't remember what that was, or find the mail.

Docxx:
       PROS:
            -  Docxx is powerfulll and farily flexbile.   You can control the
            doucmentation generated fairly well.  (Whether you can be bothered
             is another matter).

        CONS:
             -  I had to use the binary since it didn't compile.  That sort of
                 thing annoys me.
             -  It produced some incorrect output.
             -  It produced lots of unnecassary output.


Koc:
       PROS:
              -  Handles cross references between seperately documented
                   libraries.  This would be usefull for us, given the
                   decentralized nature of the project.
               -  The output is very nice from a practical point of view:  You
                    first get a short discription of the object and a member
                    list, followed by the longer documentation.  You can click  
                    on links in the short documentation to get to the long. 
                    Also it produces an "htmlized heade".  That is it converts
                    the header into HTML (putting hyperlinks in and everythng)

        CONS:
               -  Very inflexible.  Kdoc must see some C++ construct it
                    recongizes to produce any output.  With docxx you can put
                    your own documentation in arbtrary places if you want.
               -   It WILL NOT document anything outside of a C++ class.
                    This is bad enough for my Layer O code, but Kdoc would be
                     useless for layer P.
                -   Had to hack Kdoc to make LaTeX work.


Thanks.

Bye.