C++ Source Code Documentation for large project

[Axter]

I normally use a program call Doxygen to document my source
code.(http://www.stack.nl/~dimitri/doxygen)

This method works great for small and medium size projects, and you can
get good documentation like the following:
http://axter.com/smartptr

Now I'm on a client site, and I'm trying to create the same type of
documentation on a very large project.
I ran the Doxygen program, and it ran for over 16 hours, before I had
to kill it.

Before I look into a different solution, I wanted to see if anyone else
has had the same problem in the past, and what type of solution was
used to document the source code for a large project (suite) that has
over 11,000 source files.

Sorry if OT

----------------------------------------------------------------------------------------
David Maisonave
http://axter.com

Top ten member of C++ Expert Exchange:
http://www.experts-exchange.com/Cplusplus
----------------------------------------------------------------------------------------

 

[Noah Roberts]

I normally use a program call Doxygen to document my source
code.(http://www.stack.nl/~dimitri/doxygen)

This method works great for small and medium size projects, and you can
get good documentation like the following:
http://axter.com/smartptr

Now I'm on a client site, and I'm trying to create the same type of
documentation on a very large project.
I ran the Doxygen program, and it ran for over 16 hours, before I had
to kill it.

Before I look into a different solution, I wanted to see if anyone else
has had the same problem in the past, and what type of solution was
used to document the source code for a large project (suite) that has
over 11,000 source files.

No, I haven't.

I would think that a large project like that would be split into
several, distinct pieces that could be documented independently. I
know, many such projects are not and are just big monstrosities that
got out of hand....maybe it is time for some refactoring.

 

[red floyd]

I normally use a program call Doxygen to document my source
code.(http://www.stack.nl/~dimitri/doxygen)

This method works great for small and medium size projects, and you can
get good documentation like the following:
http://axter.com/smartptr

Now I'm on a client site, and I'm trying to create the same type of
documentation on a very large project.
I ran the Doxygen program, and it ran for over 16 hours, before I had
to kill it.

Before I look into a different solution, I wanted to see if anyone else
has had the same problem in the past, and what type of solution was
used to document the source code for a large project (suite) that has
over 11,000 source files.

I'd like to point out that Xerces-C, the XML parser from Apache, uses
Doxygen for its documentation. I don't believe it's on the order of 11K
source files, though.

 

[Axter]

No, I haven't.

I would think that a large project like that would be split into
several, distinct pieces that could be documented independently. I
know, many such projects are not and are just big monstrosities that
got out of hand....maybe it is time for some refactoring.

I'm trying to avoid creating an independent help file for each sub
project, because I would have to create over 300 help documents, and
IMHO, its usage wouldn't be practical.
I want to create one help document for the entire suite, so I'm trying
to run doxygen from the main tree.
The main tree is broken down into three sections:
SrcClient (162-projects)
Common (94-projects)
SrcServer (109-projects)

I guess my other alternative is to try to document the three sections
independently, but that will still give me about 3900 source files per
section.
And I think Doxygen would still have a hard time processing that many
files.

I've had two other clients which also had suites of this size, and
they also lacked source code documentation.
I would think someone by know would have already come up with a
solution to document such monster suites.

 

[Noah Roberts]

I'm trying to avoid creating an independent help file for each sub
project, because I would have to create over 300 help documents, and
IMHO, its usage wouldn't be practical.
I want to create one help document for the entire suite, so I'm trying
to run doxygen from the main tree.
The main tree is broken down into three sections:
SrcClient (162-projects)
Common (94-projects)
SrcServer (109-projects)

If the package separation is decent you should only need to document
the three sections independantly for the developers working on them and
then the public interface used by others. Much easier to view
documentation that way that to have one large monolithic thing you have
to hunt through.

 

[ma740988]

This method works great for small and medium size projects, and you can
get good documentation like the following:
http://axter.com/smartptr

Very interesting.

I didn't realize there was that many smart pointers. reference
counted smart/ versus just _smart_ versus etc..

 

[Phlip]

I didn't realize there was that many smart pointers. reference
counted smart/ versus just _smart_ versus etc..

Hmm...

- pointers which cannot be used inside containers
- auto_ptr - essentially the weakest possible smart pointer
- pointers which share, and which can be used inside containers
- reference counting smart pointers
- RCSPs that store their count in their target objects
- RCSPs that use virtual AddRef() and Release() methods
- RCSPs that store their count in a new int

Thence, smart pointers that can survive cycles, possibly using Garbage
Collection techniques.

Thence, smart pointers that can inform all their clients when one client
decides to kill the target item, and all other clients must be informed.

Thence, smart pointers that may contain arrays returned by new[].

Did I miss any?

 

[Axter]

I didn't realize there was that many smart pointers. reference
counted smart/ versus just _smart_ versus etc..

Hmm...

- pointers which cannot be used inside containers
- auto_ptr - essentially the weakest possible smart pointer
- pointers which share, and which can be used inside containers
- reference counting smart pointers
- RCSPs that store their count in their target objects
- RCSPs that use virtual AddRef() and Release() methods
- RCSPs that store their count in a new int

Thence, smart pointers that can survive cycles, possibly using Garbage
Collection techniques.

Thence, smart pointers that can inform all their clients when one client
decides to kill the target item, and all other clients must be informed.

Thence, smart pointers that may contain arrays returned by new[].

Did I miss any?

Yes many.

I notice you're referring to all the reference smart pointers as
reference counting.
However, that is just one type of reference smart pointer.
Reference smart pointers that store the count in the target object are
normally called reference intrusive smart pointers, and they may or may
not use a count method.

Reference link smart pointers don't use a reference count at all.

Clone smart pointers (deep-copy) don't share the pointer, and perform a
deep copy when passed by value.

The following smart pointer also has a COW smart pointer policy by
default:
http://axter.com/smartptr

This COW smart pointer is a mix between a shared smart pointer and a
clone smart pointer.

You can also have a synchronized smart pointer.
http://axter.com/smartptr/structintrusive__lock__policy.htm
Using the above policy you lock the smart pointer and the pointee at
the same time, so you can safely use the pointee in a multithread
environment.

You can have smart pointers with value semantic for comparison
operator, which would allow you to use the smart pointer in a sorted
container.
http://axter.com/smartptr/structvalue__comparsion__semantic__policy.htm

And much more...

You can create over 250 different types of smart pointers just using
the default policies that are included in this smart pointer.
And boost has a few more
http://www.boost.org/libs/smart_ptr/smart_ptr.htm


----------------------------------------------------------------------------------------
David Maisonave
http://axter.com

Top ten member of C++ Expert Exchange:
http://www.experts-exchange.com/Cplusplus
----------------------------------------------------------------------------------------

 

[Imre Palik]

- pointers which cannot be used inside containers
- auto_ptr - essentially the weakest possible smart pointer
- pointers which share, and which can be used inside containers
- reference counting smart pointers
- RCSPs that store their count in their target objects
- RCSPs that use virtual AddRef() and Release() methods
- RCSPs that store their count in a new int

Thence, smart pointers that can survive cycles, possibly using Garbage
Collection techniques.

Thence, smart pointers that can inform all their clients when one client
decides to kill the target item, and all other clients must be informed.

Thence, smart pointers that may contain arrays returned by new[].

Did I miss any?

Yes. What about those that won't do any resource management, but they are
smart in some other way? E.g., locking proxies.

ImRe