incubator-stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marc Betz <mb...@roguewave.com>
Subject RE: stdcxx documentation format
Date Tue, 06 Sep 2005 16:24:08 GMT
Martin,

If I were estimating it for a docs person, I would think in terms of several
weeks of work. The stdlib reference, as you know, is large. A cut and paste
approach has a number of factors that would make it both tedious and time
intensive: care in accurately matching each description with its method
signature; chopping the continuous lines of the current documentation into
80 character line lengths for insertion into the code; adding doxygen
comment tagging to each description. Then, too, there is the issue of
conditional compilation, which doxygen can deal with, but the technique for
doing that is a bit complex. We do not really deal with conditional
compilation in our current documentation, but I think we will have to with
doxygen because it preprocesses the code before extracting the
documentation. (Actually, you can disable preprocessing, but I am guessing
that would create more problems than it would avoid.)

Maybe Alessio has some automation solutions in mind that would reduce the
time. I can think of a few possibilities, but I am uncertain how truly
effective they would be. It might be that the effort to get the automation
working well would exceed the time ultimately saved.

Marc

-----Original Message-----
From: Martin Sebor [mailto:sebor@roguewave.com] 
Sent: Tuesday, September 06, 2005 9:10 AM
To: Marc Betz
Cc: stdcxx-dev@incubator.apache.org
Subject: Re: stdcxx documentation format


Marc Betz wrote:
> Martin,
> 
> Doxygen does all the same kind of linking we do in our reference 
> guides, and then some. The output, too, is very configurable, with the 
> exception on the look and feel, which was a problem for us in terms of 
> fitting in with our other product documentation, but would not matter 
> to the open source community. I think putting the documentation in 
> source code comments is a lovely idea, but I am pretty sure Alessio 
> does not have a good understanding of how big a task he is proposing.

What would be your estimate in terms of man hours?

Martin

> 
> Marc
> 
> -----Original Message-----
> From: Martin Sebor [mailto:sebor@roguewave.com]
> Sent: Tuesday, September 06, 2005 8:23 AM
> To: stdcxx-dev@incubator.apache.org
> Cc: Marc Betz
> Subject: Re: stdcxx documentation format
> 
> 
> [responding to stdcxx-dev@incubator.apache.org]
> 
> Alessio Marchetti wrote:
> 
>>Martin Sebor wrote:
>>
>>
>>>>As far as the presentation I will easily be able to use a pretty 
>>>>standard stylesheet at first, then I could customize it to match the
> 
> 
>>>>Apache look&feel.
>>>
>>>
>>>
>>>Excellent!
>>>
>>>Martin
>>>
>>>
>>
>>Now I'm thinking about the process that the documentation creation 
>>should follow.
>>
>>I have in mind two different processes for the reference guide and for 
>>the other docs (User Guide, FAQ, Technical notes, Help for people 
>>wanting to contribute to the project, etc.).
> 
> 
> There are a couple of projects in use at Apache: Forrest and Maven. I 
> haven't used either but I believe a lot of the Web pages around here 
> are generated by Forrest.
> 
> 
>>While the other docs are best single-sourced from XML content
>>(DocBook,
>>as most open -- and closed --- source projects are converting to it 
>>right now), the reference guide (until the days of literate
> 
> programming
> 
>>will come...) is better implemented with a Doxygen-like process, that
>>is: put the documentation in the source code.
>>
>>I'm sure this is the best way to proceed, because it will
>>substantially
>>increase the probability to have updated documentation.
>>
>>In this scenario, the existing UG will be migrated to DocBook (with 
>>Marc's scripts or with new ones), while the existing RG will be 
>>copy&paste'd (I suppose I will volounteer to do it...) into the
> 
> sources.
> 
>>What do you think?
> 
> 
> Going the Doxygen route is definitely very appealing for new code, but 
> converting the existing sources would be a huge amount of work.
> 
> The Class Reference is in a pretty good shape with tables, cross 
> references, etc. How easily could we preserve all that? How hard to 
> read and maintain would it make the sources?
> 
> I guess I need to look at some existing projects that use Doxygen 
> extensively to get a better feel for what it can do (my experience 
> with Doxygen is limited to that of a user of the final product). Do 
> you have any pointers? If you'd like to put together a prototype of a 
> few non-trivial pages that would be even better.
> 
> FWIW, I've started using simple Doxygen-style documentation in the new 
> test suite driver. The idea is to start with it as the guinea pig 
> before making a decision on the library. Any help here is also welcome 
> :)
> 
> Martin

Mime
View raw message