incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Andrew Black <abl...@roguewave.com>
Subject Re: Exec utility test group reporting
Date Tue, 28 Aug 2007 16:55:34 GMT
Mark Brown wrote:
>> -----Original Message-----
>> From: ablack@roguewave.com
>> Sent: Mon, 27 Aug 2007 09:11:51 -0600
>> To: stdcxx-dev@incubator.apache.org
>> Subject: Re: Exec utility test group reporting
>>
>> Greetings Mark
>>
>> At this point, the validity, usability and accuracy of the Doxygen
>> comments in the exec utility is a theoretical exercise, as I don't think
>> anyone's ever taken the step of generating the documentation pages from
>> the source files.  That said, I've installed doxygen locally, and will
>> share the results if I have time to play with it.
> 
> Well, I tried generating documentation for the stdcxx/util directory to see how Doxygen
does. The result is published on my home page: http://mark.g.brown.googlepages.com/stdcxxutil.
This is my first attempt to use the site so pardon the appearance of the entry page. In my
opinion, it doesn't look half bad, don't you think?

Ascetically the pages look decent (with the exception of a 404 on
http://mark.g.brown.googlepages.com/structtarget__opts.html ), however
they feel a little light on content.  Is there a switch to get doxygen
to generate the documentation for variables and functions outside of
classes?  The bulk of the documentation for the exec utility is in these
areas, rather than the structs which are used to pass data around.  (Is
there a C mode that you could force doxygen to use?  The exec utility
was written as a C program, though the files were given a .cpp suffix so
they could build with the infrastructure.)

> 
>> It would likely make sense to eventually store the generated docs
>> somewhere in subversion, but the potential problem of documentation
>> drift exists.  I suppose this shouldn't count as a strike against using
>> Doxygen, as that potential exists for all documentation.
> 
> Would generating the documentation automatically be a solution?

That would be a solution, but as best I can tell, you'd have to do the
regeneration on the subversion server as part of a commit script, and I
don't know if we have the ability to set such things up.

--Andrew Black

Mime
View raw message