stdcxx-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Eric Lemings" <Eric.Lemi...@roguewave.com>
Subject RE: Doxygen possible in STDCXX?
Date Wed, 07 May 2008 18:09:16 GMT
 

> -----Original Message-----
> From: Martin Sebor [mailto:msebor@gmail.com] On Behalf Of Martin Sebor
> Sent: Wednesday, May 07, 2008 10:52 AM
> To: Eric Lemings
> Cc: Marc Betz
> Subject: Re: Doxygen possible in STDCXX?
> 
> Eric Lemings wrote:
> >  
> > I would post this to the dev list but I wanted to get 
> "heads up" before
> > doing so and I don't recall what conclusions were drawn, if 
> any, from
> > past discussions.
> 
> Doesn't matter. You can always ask on the list.
> 
> >  
> > Are there any plans for using Doxygen in STDCXX?  I think 
> the answer is
> > no but I don't think there is a reason not to.  Is there?
> 
> Only for the test driver, as a proof of concept. In fact, I was
> just thinking I should suggest to you to take the lead on it :)

A proof-of-concept using a small component of the test driver would
only require a few hours of investment, provided the right component
is selected.  (The whole test driver would require a few days of
work I'm guesstimating.)

I would suggest using the printf directives (STDCXX-871) but there's
no C++ code (or not enough) related to that component to use as a
proof-of-concept.

I see that many of the rwtest header files already contains lots of
inline doc comments though the source files do not.  Has a
proof-of-concept already been started?  Should I create a Jira issue
to complete this proof-of-concept?  Should I submit changes to the
4.3.x branch?

Brad.

> 
> >  
> > If we were to use it, I was just thinking about one concern I think
> > Martin has had in the past.  Specifically putting 
> documentation in the
> > header files.  Indeed a valid concern.  I was just thinking that the
> > source files would contain all of the documentation since 
> they're only
> > compiled once the impact on builds is minimal.  And I am pretty sure
> > that code contained in the headers can be labeled such that it is
> > actually documented in the source files.  For example, 
> src/bitset.cpp
> > would document code contained in include/bitset (and 
> associated implicit
> > includes) as well as the source file itself.
> >  
> > I think this would work and it could be migrated on a 
> file-by-file basis
> > just like I'm doing with the old Perforce tests.
> 
> Marc and I brainstormed about how to deal with the library headers
> a couple of months ago and reached a similar conclusion, that the
> safest approach would be to completely decouple the Docxygen
> sources from the library headers into files of their own.
> 
> Unfortunately, none of us (TechDocs or Development) has the
> bandwidth to undertake a project of this magnitude for the
> existing stdcxx docs.
> 
> Martin
> 

Mime
View raw message