ccdoc home page Ccdoc Issues

ccdoc home page
Ccdoc Issues
All
Summary
Joe Linoff
$Date: 2004/09/30 16:09:24 $
$Revision: 1.35 $

This page keeps track of issues related to ccdoc as they come up. If you click the Summary link at the top of the page it will take you to a summary page. If you click on the status types (such as OPEN) it will take you to a page that lists only issues with that status.

The status field contains either CLOSED, FIXED or OPEN.

CLOSED - This issue did not require a change to ccdoc.
FIXED - This issue was fixed in a release of ccdoc.
OPEN - This issue is pending.

These pages were automatically created by a perl script called make_issues.pl that is freely available by clicking here the input to the script is a text file.

Status Summary

Status	Number
CLOSED	8
FIXED	144
OPEN	31
Total	183

Entry Summary

Id	Title	Status
0001	The -rootfile switch parses relative names improperly.	FIXED
0002	The ccdoc_top tage is incorrectly placed in the HEAD section.	FIXED
0003	Need a new switch, similar to -head, that inserts a file after the head tag to insert custom META elements.	FIXED
0004	HTTP server problem with uncommon extensions like .exe_gz and .taz.	FIXED
0005	Log output is not flushed properly on solaris platforms.	FIXED
0006	Tests weren't working properly.	FIXED
0007	WARNING: File '*.h' cannot be read so it will be ignored.	FIXED
0008	Turn off the ccdoc generation of special members.	FIXED
0009	Compile problem in gcc 3.0 on SuSE linux platform.	FIXED
0010	Random character appears between package name and function/macro/etc. name in the HTML title.	FIXED
0011	Instantiations of class template methods are reported as global functions.	CLOSED
0012	Ccdoc should ignore template method instantiations.	FIXED
0013	Add ccdoc to source forge.	FIXED
0014	The typedef id for function pointer doesn't get extracted properly by ccdoc.	FIXED
0015	Methods with throw clauses surrounded by parentheses don't get extracted properly by ccdoc.	FIXED
0016	Source file names of the form ../folder/file.ext don't work properly in the cmd.exe shell under windows.	FIXED
0017	Can't differentiate between different revisions of ccdoc 0.8.	FIXED
0018	Directory separators in -root names cause run time errors.	FIXED
0019	The @see directive no longer accepts user defined links.	FIXED
0020	ccdoc crashes	FIXED
0021	Report the version/revision information in the default trailer.	FIXED
0022	Centralize the version/revision information.	FIXED
0023	DOC++ vs ccdoc	CLOSED
0024	Missing comma separator in @see output for the alternative URL form.	FIXED
0025	Undocumented 0.7a feature for explicitly specifying @pkgdoc URLs is no longer supported.	FIXED
0026	Provide an expanded package contents view.	FIXED
0027	Provide a way to turn off package source.	FIXED
0028	Provide a way to turn off the default author on the package page.	FIXED
0029	Provide a way to turn off the default version on the package page.	FIXED
0030	Provide a way to turn off default description comments on the page.	FIXED
0031	Provide a way to change the "package" string in the title on package pages.	FIXED
0032	Users guide and on-help report than -norptpub is the default.	FIXED
0033	This construct is incorrectly recognized as a struct: void foo(struct bar* spam).	FIXED
0034	For -rpthpc only show packages.	FIXED
0035	ccdoc 0.7a to 08 quick reference	FIXED
0036	Comments get lost.	FIXED
0037	Change the asterisk column header to "Inherited From".	FIXED
0038	Change the Path column header to "Entity".	FIXED
0039	Performance problem in phase3.	FIXED
0040	Protected inherited methods reported.	FIXED
0041	Improve 0039 performance enhancement.	FIXED
0042	ccdoc bug notification - not correctly determining variable name	FIXED
0043	Old hash mark syntax for @see does not work.	FIXED
0044	The summary report could use a little more indenting.	FIXED
0045	The variable width font in the Code: section is not as readable as the fixed width font used in 0.7a.	FIXED
0046	The @see index doesn't seem to work.	FIXED
0047	The indenting on the contents page should be the same as the summary report.	FIXED
0048	Derived classes in namespaces are not recognized correctly.	FIXED
0049	Non-template class method instantiation not recognized correctly.	FIXED
0050	Ccdoc fails to parse methods with fct args properly.	FIXED
0051	External class method implementations with default arguments are not correctly recognized.	FIXED
0052	Backslash character definition ('\\') confuses the ccdoc scanner.	FIXED
0053	No line numbers for internal comment parsing warnings.	FIXED
0054	Serious problem with typedef of struct	FIXED
0055	ccdoc generates default special members for C style structs	CLOSED
0056	Incorrect line numbers reported in warning messages.	FIXED
0057	"Undocumented" as default short desc. in tables is confusing.	CLOSED
0058	Provide a way to turn off the default author and version for packages.	CLOSED
0059	Validate ccdoc generated HTML.	FIXED
0060	Group entries by type.	OPEN
0061	Typedef struct statement does not include struct comments.	OPEN
0062	Long entry name deforms HTML table.	OPEN
0063	Allow user defined defaults for author, short description and version.	FIXED
0064	Friend classes in namespaces are not recognized correctly.	FIXED
0065	Links from documentation in namespaces are not recognized correctly.	CLOSED
0066	The <sstream> header is not needed in phase3_html.cc.	FIXED
0067	Ccdoc does not correctly reset the access specifiers for methods in base classes that are derived as protected or private.	OPEN
0068	Core dump on solaris in the index phase.	FIXED
0069	Cannot handle construct: "Float operator/(const Float & rval)"	FIXED
0070	Users guide documentation error.	FIXED
0071	Operator keyword duplicated for method operators.	FIXED
0072	New switch to turn off sorting of class entities.	FIXED
0073	Can't tell ccdoc to ignore a privately declared default constructor.	FIXED
0074	Ccdoc cannot handle international character sets.	FIXED
0075	Ccdoc cannot handle function typedef of the form: typedef void fct(int arg1);	FIXED
0076	Conflict between -meta switch and ccdoc defined meta variables.	FIXED
0077	Ccdoc incorrectly identifies a class attribute name.	FIXED
0078	Ccdoc incorrectly identifies a variable as a function.	FIXED
0079	platform.pl cannot handle embedded parentheses.	FIXED
0080	Trim trailing spaces in path name for get_stmt_no_pkgs().	FIXED
0081	Multi-space blank lines between SHORT and LONG descriptions cause them to merge.	CLOSED
0082	Add the @since directive per the javadoc 1.2 specification.	FIXED
0083	Modify ccdoc to create a separate links page (as was done in v0.7a).	FIXED
0084	Alias @exception to @throws per javadoc 1.2.	FIXED
0085	Ccdoc not recognize default constructors with member initialization.	FIXED
0086	Comment form to handle single line suffix comments.	FIXED
0087	Exceptions were not reported as links.	FIXED
0088	An extra invalid link reported for @link references to classes.	FIXED
0089	Ccdoc short description syntax is not compliant with javadoc.	FIXED
0090	Support the {@link ...} javadoc syntax.	FIXED
0091	Constant values are not hyperlinked in the documentation for function arguments.	FIXED
0092	The @link syntax does not support the # scoping operator.	FIXED
0093	Add javadoc style doc comment inheritance.	OPEN
0094	Comment reuse for overloaded functions.	OPEN
0095	Comma's inserted for each line in @returns and @deprecated comments.	FIXED
0096	Provide an @repeat operator to avoid having to re-type comments.	OPEN
0097	Private method is reported incorrectly for overloaded methods with different scopes.	FIXED
0098	It would be a help if you made the reference red if the class cannot be found for @link.	FIXED
0099	Ccdoc does not correctly follow the standard for default constructors.	FIXED
0100	If using switch -files with a wildcard expression the first file is not processed.	CLOSED
0101	Template problem.	FIXED
0102	Returned nested classes and types in namespaces are not recognized correctly.	FIXED
0103	Invalid processing of operator~().	FIXED
0104	Invalid processing of operator&().	FIXED
0105	The javadoc @see tag defines the label part as optional.	OPEN
0106	The javadoc spec for @see allows unqualified names as well as qualified names.	OPEN
0107	javadoc # syntax is not supported in the {@link...} directive.	FIXED
0108	-rptdefasd, -rptdefsd and -rptdefv problems and suggestions	OPEN
0109	Print warnings to stderr.	FIXED
0110	Invalid processing of operator[].	FIXED
0111	Multiple link file overflow problem.	FIXED
0112	Phase 3 exception for operator\|.	FIXED
0113	Merge separate ccdoc databases.	OPEN
0114	Error processing of a operator unsigned long().	FIXED
0115	Mangled links for .\doc\ references on the command line.	FIXED
0116	The string constant "\\" isn't parsed correctly.	FIXED
0117	Class method reported as global function.	FIXED
0118	Resolve partially scoped references.	FIXED
0119	Inconsistent command line syntax for -html paths under DOS.	OPEN
0120	Add support for the proposed todo tag in javadoc.	FIXED
0121	Reuse namespace comments between packages.	OPEN
0122	Enhance template reporting.	FIXED
0123	{@link ...} not reported correctly in the @deprecated directive	FIXED
0124	Scanner condition evaluates to a constant value.	FIXED
0125	Hash mark displayed for default {@link...} reference.	FIXED
0126	CcDoc does not recognize ccdoc c++ short comment in a "typedef struct" definition.	OPEN
0127	CcDoc does not recognize recognize template derivations.	FIXED
0128	Order class entities the same way that were ordered in v07.	OPEN
0129	All subdirectories are picked up on NT when the * wildcard is specified.	FIXED
0130	Code section wraps in a strange way for small browser windows.	FIXED
0131	Support comma separated declarations.	OPEN
0132	support single-line prefix comments via //@+	OPEN
0133	Anonymous namespaces are not handled correctly.	FIXED
0134	Need a forward link to the contents section for classes and packages.	FIXED
0135	Fix the copyright notice in the code.	FIXED
0136	Ccdoc gets confused by a nested struct.	FIXED
0137	The {@link} directive does not work @param clauses.	OPEN
0138	The @see and {@link} directives do not correctly reference entities in different packages.	FIXED
0139	Core dump when an invalid package name of the form "A::B:" appears.	FIXED
0140	Core dump when a friend declaration of the form: foo&operator<< appears.	FIXED
0141	Architecture is not reflected in the bin directory name.	FIXED
0142	No man page for linux ports.	FIXED
0143	Support javadocs frames format.	OPEN
0144	Mark static members and methods in the class overview.	FIXED
0145	It is impossible to reference an operator in the @see and {@link..} directives.	FIXED
0146	Namespace processing doesn't work properly in certain cases.	FIXED
0147	Lots of compiler warnings when building ccdoc using the Borland C++ compiler.	FIXED
0148	Allow users to customize ccdoc output using a CSS file.	OPEN
0149	Template method implementations confuse ccdoc.	FIXED
0150	Make it easier to update the revision number in the source files.	FIXED
0151	Translate the generated html to other languages.	OPEN
0152	Ignore duplicate macros names.	FIXED
0153	Add a heuristic to ignore include guards and DLLIMPORT macros.	FIXED
0154	Eliminate the requirement that the -rptmac and -rptmac1 switches appear in phase 1.	FIXED
0155	Incorrect documentation when there is only one ccdoc namespace comment for namespace declarations in multiple files.	FIXED
0156	More namespace problems in r35.	FIXED
0157	In some cases operator code is being processed incorrectly.	FIXED
0158	Class method implementations are reported as global functions.	FIXED
0159	Very long names make the contents table very hard to read.	FIXED
0160	Empty function names appear under certain conditions.	FIXED
0161	Strange function names like "max)" appear sometimes.	FIXED
0162	Doxygen compatibility - support single line comments using doxygen syntax.	FIXED
0163	Doxygen compatibility - ignore the @endlink directive.	FIXED
0164	Doxygen compatibility - ignore @file comment blocks.	FIXED
0165	Doxygen compatibility - support virtual grouping of definitions.	OPEN
0166	Variable values are not reported properly when braces occur in the value.	FIXED
0167	In German we want to use embedded dots in the short description.	OPEN
0168	Slow g++ 3.2 compile of help.cc because of the large help string.	FIXED
0169	Man page has formatting problems.	FIXED
0170	Bug on NT platforms parsing command line with spaces and wildcards.	FIXED
0171	Constructors with constructed default arguments are reported with the wrong method name.	FIXED
0172	Template friend declarations are not resolved properly when packages are used.	FIXED
0173	The md5hash macro is being improperly ignored by the rptmac1 heuristic.	FIXED
0174	Bug#195282: ccdoc: FTBFS with g++-3.3	FIXED
0175	Generate an index in HTML and XML.	OPEN
0176	Enhance the table of contents for easier navigation with letter based links at the top.	OPEN
0177	Invalid link from parameter variable name to member variable.	OPEN
0178	Namespace/anonymous enum interaction bug.	OPEN
0179	Add a new @entity directive to allow referencing.	OPEN
0180	Limit the length of generated file names.	OPEN
0181	Copy constructor documented incorrectly under some conditions.	OPEN
0182	Add directory tree/outline expansion (+/-) capabilities to better organize the information.	OPEN
0183	Ccdoc started failing with a segment violation in phase 3 when processing a large system (thousands of classes) after a small change to one of the header files.	FIXED

Title:	The -rootfile switch parses relative names improperly.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/08/22
Resolved By:	Joe Linoff
Resolved On:	2001/08/22

Id: 0001
[Top]
[Summary]
[Next]

Problem Description:

Little bug: Switch '-rootfile': If there is no parh given, the first letter of filename will missing from the HTML hrefs. Eg:
'-rootfile index.html' => '<a href='ndex.html'>@root</a>' ('i' missing)
but
'-rootfile ./index.html' => '<a href='index.html'>@root</a>'

Solution Description:

Found a problem in make_file_url. The separator iterator was being incremented when the path was completely relative.

Broken Code: phase3_html.c:1845

  // ================================================================
  // Make file URL, strip off the leading directories.
  // ================================================================
  void ccdoc::phase3::html::make_file_url(string& url,string& fn) const
  {
    // Strip off the leading directories to
    // make the relative reference work.
    string::iterator itr = fn.begin();
    string::iterator relpath_itr = fn.begin();
    for(;itr!=fn.end();++itr) {
      if( '/' == *itr ) {
        relpath_itr = itr;
      }
    }
    url = "";
    for(++relpath_itr;relpath_itr!=fn.end();++relpath_itr) {
      url += *relpath_itr;
    }
  }

Fixed Code

  // ================================================================
  // Make file URL, strip off the leading dSeptember 18, 2001 (Tuesday)

The new release of ccdoc is available: "ccdoc v0.8 r18 2001/09/18".

This release fixes issues 0052 and is the first release that contains the linux port.





irectories.
  // ================================================================
  void ccdoc::phase3::html::make_file_url(string& url,string& fn) const
  {
    // Strip off the leading directories to
    // make the relative reference work.
    string::iterator itr = fn.begin();
    string::iterator relpath_itr = fn.begin();
    for(;itr!=fn.end();++itr) {
      if( '/' == *itr ) {
        relpath_itr = itr;
        ++relpath_itr; // ISSUE 001 FIX
      }
    }
    url = "";
    for(;relpath_itr!=fn.end();++relpath_itr) {
      url += *relpath_itr;
    }
  }

Title:	The ccdoc_top tage is incorrectly placed in the HEAD section.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/08/22
Resolved By:	Joe Linoff
Resolved On:	2001/08/22

Id: 0002
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Very little bug: <a name=ccdoc_top></a> is placed into the HEAD, which is not correct (according to HTML 4.0 at least, but I don't think its right for HTML 3.x). It should be pleced just *before* that <table border=0 width="100%"> in the BODY. However I don't know a browser which is confused by this.

Solution Description:

Moved <a name=ccdoc_top></a> to the BODY section.

Title:	Need a new switch, similar to -head, that inserts a file after the head tag to insert custom META elements.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/08/22
Resolved By:	Joe Linoff
Resolved On:	2001/08/22

Id: 0003
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

What is missing, a switch similar to '-head' which inserts the specified file just after the <head> tag. This is required to insert custom META elements, primary for set the charset. (Note that most browsers accepts META http-equivs in the BODY (!) so I can use -head, but its not correct HTML.)

Perhaps a -meta <file> switch?

Solution Description:

Added a -meta <file> switch that allows the user to specify a file that contains custom meta variables.

Title:	HTTP server problem with uncommon extensions like .exe_gz and .taz.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/08/22
Resolved By:	Joe Linoff
Resolved On:	2001/08/23

Id: 0004
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The HTTP server on www.joelinoff.com gives back text/html content-type for those files with uncommon extensions, like ccdoc.exe_gz, doc.tgz. It confuses many browsers. (I think the solution is to set DefaultType in the httpd.conf to application/octet-stream, unless u serve html or plain text documents with odd or no extension.)
(btw, if some users will report CRC errors in the gzipped files, this is because there is some conflict between the HTTP server and some (or only one?) proxy-es. Dont ask why, I got partial-content (HTTP 206) without the last few kbytes of files (=> gunzip detects CRC error), then decided to bypass the cache-proxy.)

I completely agree. I have been trying to work with my domain hosting service to correct this (Earthlink) but they are very slow to respond.

Solution Description:

I resolved this by renaming the archives that were causing problems. Apparently the ".gz" extension does the right thing.

Title:	Log output is not flushed properly on solaris platforms.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/22
Resolved By:	Joe Linoff
Resolved On:	2001/08/22

Id: 0005
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Part of the log file is missing on the solaris platforms because the s_log global variable is not flushed at the end of the program.

Solution Description:

This was resolved by flushing the s_log object before the program exits.

Title:	Tests weren't working properly.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/22
Resolved By:	Joe Linoff
Resolved On:	2001/08/22

Id: 0006
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Tests are being reported as successful when they are not.

Solution Description:

There was a bug in the test.pl file that caused all tests to pass.

Title:	WARNING: File '*.h' cannot be read so it will be ignored.
Status:	FIXED
Reported By:	Yuriy Stul
Reported On:	2001/08/23
Resolved By:	Joe Linoff
Resolved On:	2001/08/23

Id: 0007
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Wildcards do not work in my cmd.exe shell. Here is my example:
    C:> ccdoc.exe -db LB.db -pkg LBTools *h
    WARNING: File '*.h' cannot be read so it will be ignored.

Solution Description:

Fixed in r10.
I modified the MSVC version of the program to attempt to process wildcards if the attempt to open the specified file fails. The -files switch still works.
When I originally closed this issue, I used the following reasoning.
Wildcards do not work in the cmd.exe shell on Windows platforms because it does not expand them. Instead it expects the application to do the expansion.
Ccdoc cannot do that because a user can run many different shells on Windows platforms, such as: ksh, rsh and tcsh (I use tcsh). Most of those shells (in fact all of them execept cmd.exe) expand wildcards before passing the the program.
Unfortunately, ccdoc can't tell the difference a legitimate file name with a * or ? in it from the tcsh and a wildcard request from the cmd sheel so you have to tell it using the -files switch.
You can work around this problem by using the new -files switch as follows:
    C:> DIR \B *.h > hfiles.txt
    C:> ccdoc -db foo.db -pkg foo -files hfiles.txt

Title:	Turn off the ccdoc generation of special members.
Status:	FIXED
Reported By:	Martin Trappel
Reported On:	2001/08/23
Resolved By:	Joe Linoff
Resolved On:	2001/08/23

Id: 0008
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Ccdoc seems to generate automatic comments for Standard Copy Constructor, Destructor and Assignment Operator.
Can I disable this, since I have a few classes where I do not have these and I don't quite see the point in having doc for non-existant members?

This was originally added because of request from Lou Sanchez-Chopitea because, according to the standard, these special members always exist whether you declare them or not.
I agree with your point that you should not be forced to see them unless you want to and will look into providing a switch that gives you the control to turn the reporting of them on or off.

Solution Description:

Added the -[no]cdsm switches to phase 1 to allow users to control whether or not default special members are created.

Title:	Compile problem in gcc 3.0 on SuSE linux platform.
Status:	FIXED
Reported By:	Michael Davis
Reported On:	2001/08/23
Resolved By:	Joe Linoff
Resolved On:	2001/08/23

Id: 0009
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

We use gcc 3.0 on a SuSE linux platform here, and your code compiled with only one glitch. Here is a patch should you want it:

*** phase3_html.cc.orig Thu Aug 23 09:52:22 2001
--- phase3_html.cc      Thu Aug 23 09:36:43 2001
*************** void ccdoc::phase3::html::write_class_de
*** 476,482 ****
        --xitr;
        make_tag_id(*xitr,prev_tag);
        }
!       if( itr ) {
        vector<statement::base*>::iterator xitr = itr;
        ++xitr;
        if( xitr != contents.end() ) {
--- 476,482 ----
        --xitr;
        make_tag_id(*xitr,prev_tag);
        }
!       if( itr != contents.end() ) {
        vector<statement::base*>::iterator xitr = itr;
        ++xitr;
        if( xitr != contents.end() ) {

Solution Description:

Thank you. I have updated and released the fix.

Title:	Random character appears between package name and function/macro/etc. name in the HTML title.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/08/23
Resolved By:	Joe Linoff
Resolved On:	2001/08/23

Id: 0010
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Random character appears between package name and function/macro/etc. name in the HTML title.
Eg. this is the title for function RcMalloc in rcheap.h:
  <title>ccdoc RcMalloc rcheap.h:C:function</title>
'C' should not be there.

Solution Description:

This problem occurred because the lineno was being appended to the output string used for the title as an integer rather than a string in phase3_html.cc at line 2169.

Title:	Instantiations of class template methods are reported as global functions.
Status:	CLOSED
Reported By:	Joe Linoff
Reported On:	2001/08/24
Resolved By:	Joe Linoff
Resolved On:	2001/08/24

Id: 0011
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In the following example, the instantiation of the template constructor is incorrectly reported as a global function.
    template <class T>
    class A {
    public:
      A();
    };

    // Instantiation is incorrectly reported as
    // a global function.
    template <class T>
    A<T>::A()
    {
    }

Solution Description:

This occurs because ccdoc attempts to do a name resolution to determine where the instantiation belongs so it tries to look up A<T> and can't find it.
The best way to work around this problem is to tell ccdoc to ignore the template method instantiations as shown below:
    template <class T>
    class A {
    public:
      A();
    };

    #if !defined(__ccdoc__)
    // Instantiation is incorrectly reported as
    // a global function.
    template <class T>
    A<T>::A()
    {
    }
    #endif
Meanwhile, I am looking at adding a feature to ccdoc to tell it to ignore template method instantiations (without ignoring template functions), see issue 0012.

Title:	Ccdoc should ignore template method instantiations.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/24
Resolved By:	Joe Linoff
Resolved On:	2003/02/17

Id: 0012
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

See issue 0011 for details of the problem. Ccdoc should have a switch that allows users to tell it to turn off (or on) the recognition of template method instantiations.

Solution Description:

Fixed in r33 and verified by test 69.
See issue 0149 for more details.

Title:	Add ccdoc to source forge.
Status:	FIXED
Reported By:	Scott MacDiarmid
Reported On:	2001/08/24
Resolved By:	Joe Linoff
Resolved On:	2002/01/02

Id: 0013
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

I am sure you have been asked this before, but have you ever considered moving this project to SourceForge (http://www.sf.net)? It provides bug tracking, forums, and version control. I find it useful from both sides of the coin. Meaning as a developer and an end-user. As a developer it allows people to easy submit bugs to me, ask me question and it also provides CVS for good version control. As an end user I can follow what a project is doing very easily. The only catch is you would have to put it under an open source license. Anyway, just a thought.

I think that this is a great idea and have initiated the process. I will close this issue when the transfer is complete.

Solution Description:

I finally got around to it. See http://ccdoc.sourceforge.net.

Title:	The typedef id for function pointer doesn't get extracted properly by ccdoc.
Status:	FIXED
Reported By:	Chi-Fung Fan
Reported On:	2001/08/24
Resolved By:	Joe Linoff
Resolved On:	2001/08/24

Id: 0014
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The typedef id for function pointer doesn't get extracted properly by ccdoc. Example:
    /** Zero-argument const method type for Node */
    typedef Node* (Node:*NodeConstMeth) () const;
Ccdoc will generate an entry with 'const' instead of NodeConstMeth.

This is a serious problem, I will look into it as soon as possible.

Solution Description:

The problem was in phase1_parser.c. The parse_typedefs id heuristic did not how to deal with a trailing const keyword.

Title:	Methods with throw clauses surrounded by parentheses don't get extracted properly by ccdoc.
Status:	FIXED
Reported By:	Chi-Fung Fan
Reported On:	2001/08/25
Resolved By:	Joe Linoff
Resolved On:	2001/08/27

Id: 0015
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Methods with throw claused don't extracted properly by ccdoc. Example:
  void PlotDown(const doc::CC* pCC) const
    throw (RunTimeError);
I will fix this as soon as possible. Meanwhile, here is a workaround that you can use.
  void PlotDown(const doc::CC* pCC) const
#if !defined(__ccdoc__)
    throw (RunTimeError)
#endif
    ;

Solution Description:

Fixed in r5.
This problem occurred because the get_fct_id() heuristic in phase1_parser assumed that the trailing set of outermost parentheses defined the function argument list. I changed it look for the trailing set of outermost parentheses before a "throw" keyword.

Title:	Source file names of the form ../folder/file.ext don't work properly in the cmd.exe shell under windows.
Status:	FIXED
Reported By:	Yuriy Stul
Reported On:	2001/08/26
Resolved By:	Joe Linoff
Resolved On:	2001/08/28

Id: 0016
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Source file names of the form ../folder/file.exe don't work properly. The error message that it report is:
  The instruction at "0x00402330" referenced memory at "0x6e64658f".
  The memory could not be read.
I need your help. I cannot reproduce this bug. I have created half a dozen test cases and they all work.
Here are two examples of the command lines I was testing:
  ..\bin_opt_msvc_MSWin32-4.0\ccdoc -db ..\test\test.db -html ..\test\html\ ..\sources\s1.h ..\sources\s2.h

  AND

  ..\bin_opt_msvc_MSWin32-4.0\ccdoc -db ../test/test.db -html ../test/html/ ../sources/s1.h ../sources/s2.h
I tried multiple levels of directories. I tried different source file extensions and everything else I could think of.
All of this testing was done under Win2K using the MS-DOS command interpreter (cmd.exe).
Can you help figure out what am I doing wrong so that I can track down and fix this problem?

Solution Description:

Fixed in r8.
First, my thanks to Yuriy for helping me track this down.
This was a different manifestation of issue 0020. The fix was the same.

Title:	Can't differentiate between different revisions of ccdoc 0.8.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/26
Resolved By:	Joe Linoff
Resolved On:	2001/08/26

Id: 0017
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

It is difficult to distinguish between different versions of ccdoc 0.8.

I need to a -version switch to report the version/revision of the program.

Solution Description:

Fixed in r5.
Added the -version switch. Deprecated the -cid switch.

Title:	Directory separators in -root names cause run time errors.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/27
Resolved By:	Joe Linoff
Resolved On:	2001/08/27

Id: 0018
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Directory separators in -root names cause run time errors. If you use a directory separator in a -root name, it confuses ccdoc into thinking there is a directory when there isn't which causes a run-time error.

Solution Description:

Fixed in r6.
Added '/' and '\' filtering in ccdoc::phase3::html::format_name().

Title:	The @see directive no longer accepts user defined links.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/27
Resolved By:	Joe Linoff
Resolved On:	2001/08/27

Id: 0019
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The @see directive no longer accepts user defined links. In the previous version of ccdoc I could put in a direct link as follows:
@see <a href=mywebpage.html>Useful Stuff</a>
This is an oversight. It will be fixed immediately.

Solution Description:

Fixed in r7.
Modified the scanner to accept @see arguments that begin with a '<'. Modified the html generator to output these without interpretation.

Title:	ccdoc crashes
Status:	FIXED
Reported By:	Chi-Fung Fan
Reported On:	2001/08/27
Resolved By:	Joe Linoff
Resolved On:	2001/08/28

Id: 0020
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Both MSVC and cygwin versions of ccdoc crashed on generating docs for my program source. Attached is the debug messages before ccdoc dumped core.

I noticed that the offendng file that caused the core dump is the last file 'src/ScribDoc.h'. If I move it to be the first input file, everythinkg runs ok. This is also the workaround for me.

What information do you need to debug this problem?

ccdoc -v -db doc/webdocs/ccdoc.db -pkg Util include/mathpack/convolution.h include/mathpack/geometry.h include/ctl/iterator.h src/plot.h
db: read begins
db: does not exist
db: read ends
phase1: begins
phase1: parsing 'include/mathpack/convolution.h' ...
phase1: parsing 'include/mathpack/geometry.h' ...
phase1: parsing 'include/ctl/iterator.h' ...
phase1: parsing 'src/plot.h' ...
phase1: ends
db: write begins
db: writing 146 statements
db: write ends
ccdoc -v -db doc/webdocs/ccdoc.db -pkg Scribble src/navigator.h src/pager.h src/charannotvw.h src/drawtool.h src/presenter.h
db: read begins
db: read ends
phase1: begins
phase1: parsing 'src/navigator.h' ...
phase1: parsing 'src/pager.h' ...
phase1: parsing 'src/charannotvw.h' ...
phase1: parsing 'src/drawtool.h' ...
phase1: parsing 'src/presenter.h' ...
phase1: ends
db: write begins
db: writing 406 statements
db: write ends
ccdoc -v -db doc/webdocs/ccdoc.db -pkg Scribble src/definitions.h src/annottempl.h src/annotation.h src/chardefinitions.h src/dynamics.h
src/doctypes.h src/visitor.h src/docreader.h src/docwriter.h src/tablet.h src/glyph.h src/cc.h src/token.h src/page.h src/ScribDoc.h
db: read begins
db: read ends
phase1: begins
phase1: parsing 'src/definitions.h' ...
phase1: parsing 'src/annottempl.h' ...
phase1: parsing 'src/annotation.h' ...
phase1: parsing 'src/chardefinitions.h' ...
phase1: parsing 'src/dynamics.h' ...
phase1: parsing 'src/doctypes.h' ...
phase1: parsing 'src/visitor.h' ...
phase1: parsing 'src/docreader.h' ...
phase1: parsing 'src/docwriter.h' ...
phase1: parsing 'src/tablet.h' ...
phase1: parsing 'src/glyph.h' ...
phase1: parsing 'src/cc.h' ...
phase1: parsing 'src/token.h' ...
phase1: parsing 'src/page.h' ...
phase1: parsing 'src/ScribDoc.h' ...
phase1: ends
db: write begins
db: writing 1994 statements
db: write ends
      0 [main] ccdoc 94223783 open_stackdumpfile: Dumping stack trace to CCDOC.EXE.stackdump
/cygdrive/c/CHIFUNG/BIN/mkscribdocs.sh: line 63: 94223783 Segmentation fault      (core dumped) ccdoc -db doc/webdocs/ccdoc.db
root.txt
      0 [main] ccdoc 603763 open_stackdumpfile: Dumping stack trace to CCDOC.EXE.stackdump
/cygdrive/c/CHIFUNG/BIN/mkscribdocs.sh: line 64: 603763 Segmentation fault      (core dumped) ccdoc -db doc/webdocs/ccdoc.db -index
      0 [main] ccdoc 94223007 open_stackdumpfile: Dumping stack trace to CCDOC.EXE.stackdump
/cygdrive/c/CHIFUNG/BIN/mkscribdocs.sh: line 70: 94223007 Segmentation fault      (core dumped) ccdoc -db doc/webdocs/ccdoc.db
-html doc/webdocs/ -header root_hdr.txt -srcurl ../../ -root Scribble

Solution Description:

Fix in r8.
Dangling prefix comment statements at the end of db caused an iteration to extend past the end of a collection in database.cc around line 400.

Title:	Report the version/revision information in the default trailer.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/28
Resolved By:	Joe Linoff
Resolved On:	2001/08/28

Id: 0021
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Report the version/revision information in the default trailer. This makes error reporting easier.

Solution Description:

Fixed in r8.

Title:	Centralize the version/revision information.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/28
Resolved By:	Joe Linoff
Resolved On:	2001/08/28

Id: 0022
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Currently there are several references to "0.8" in phase3_html.c and in switches.cc. These should be centralized to make maintenance easier.

Solution Description:

Fixed in r8.
All references to version are now funneled through ccdoc::switches::version().

Title:	DOC++ vs ccdoc
Status:	CLOSED
Reported By:	Bragas
Reported On:	2001/08/28
Resolved By:	Joe Linoff
Resolved On:	2003/02/18

Id: 0023
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

I'm wondering if you couldn't merge your project with DOC++. They look very similar and joining your efforts could help creating even better tool (best in its category ?).
I'm not DOC++ developer and this is just my private impression.

That is an interesting suggestion. I never really gave it much thought because there are a large number of documentation generation tools out there (see my other tools page) and I have no idea which ones are suitable for merging.
As far as I am concerned, the DOC++ developers (or anyone else for that matter) are free to take the ccdoc code and incorporate it into their system(s). I would be happy to support them in that effort. Furthermore, if they showed sufficient commitment to my goal of improving documentation in the C++ community for free, I would be happy to hand it over completely.

Solution Description:

Surveyed current ccdoc users and asked whether they wanted this project merged with Doxygen or DOC++. All (100%) of the respondents said no because they felt that the tools served different needs. Ccdoc was viewed as an interface documentation tool and doxygen was viewed as a source code documentation tool. In many cases, folks used both.

Title:	Missing comma separator in @see output for the alternative URL form.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/08/28
Resolved By:	Joe Linoff
Resolved On:	2001/08/28

Id: 0024
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The @see directive does not correct separate entries with commas if there an alternative form URL specified.

Solution Description:

Fixed in r9.
Forgot to output leading comma's for the alternative URL form of the @see directive.

Title:	Undocumented 0.7a feature for explicitly specifying @pkgdoc URLs is no longer supported.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/28
Resolved By:	Joe Linoff
Resolved On:	2001/08/28

Id: 0025
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In version 0.7a, ccdoc supported an undocumented syntax for the @pkgdoc directive that allowed the user to specify a custom URL. The syntax looked like this:
    /** @pkgdoc A.B ../A_B.html*/
Ccdoc would create the link using the standard package name and substitute in the specified link. We are using that feature extensively. Will it be supported in v0.8?

Yes. This is an oversight. All features that ccdoc can reasonably support will be supported.

Solution Description:

Fixed in r9.
Added support for the two argument form of @pkgdoc and documented it in the on-line help and in the users guide.

Title:	Provide an expanded package contents view.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0026
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

This would replace the tree view in the previous version. Basically it would expand the contents path hierarchically (the same way it is done in the class summary) with the type, scope and short description.

I think that this is a great idea. The switch name will be something like -[no]rpthpc (hierarchical package contents).

Solution Description:

Fixed in r10.
I implemented the -[no]rpthpc. It reports the hierarchical class structure of each package. I liked the format so much that I made it the default.
I also added the -[no]rptcsd to allow you to control whether details are reported on the class summary page (report class summary details).

Title:	Provide a way to turn off package source.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0027
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The source entry on the package page always points to a ccdoc db file. This is not useful to casual readers.

I agree. I will remove this from the next release.

Solution Description:

Fixed in r10.
Completely removed source statements for packages. The db reference does not make sense for users.

Title:	Provide a way to turn off the default author on the package page.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0028
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Reporting unascribed as the default package author when the author is not specified is not really useful in our environment. Can I turn this default handling off?

Not right now, I will add a switch called -[no]rptdpa (default package author) to give you that control.

Solution Description:

Fixed in r10.
Added the -[no]rptdpa switches. The default is -norptdpa.

Title:	Provide a way to turn off the default version on the package page.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0029
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Reporting unknown as the default package version when the version is not specified is not really useful in our environment. Can I turn this default handling off?

Not right now, I will add a switch called -[no]rptdpv (default package version) to give you that control.

Solution Description:

Fixed in r10.
Added the -[no]rptdpa switches. The default is -norptdpv.

Title:	Provide a way to turn off default description comments on the page.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0030
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Reporting undocumented as the default package comment when the comment is not specified is not really useful in our environment. Can I turn this default handling off?

Not right now, I will add a switch called -[no]rptdpd (default package comment) to give you that control.

Solution Description:

Fixed in r10.
Added the -[no]rptdpd switches, made -norptdpd the default.

Title:	Provide a way to change the "package" string in the title on package pages.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0031
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In our environment packages have different semantics, some of them are subsystems, others are packages and still others are layers. I would like to be able to change the title on the package page to reflect this.

This is a good idea. I will add a @pkgdoctid directive that allows you to specify the title tag that ccdoc writes out. This was not possible in earlier versions because they use GIF images but in the new version it is straightforward.

Solution Description:

Fixed in r10.
Added the @pkgdoctid directive. See the on-line help or the users guide for additional details.

Title:	Users guide and on-help report than -norptpub is the default.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/08/29
Resolved By:	Joe Linoff
Resolved On:	2001/08/29

Id: 0032
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Minor documentation nit, help and the users guide report that -norptpub is the default when the real default is -rptpub.

Solution Description:

Fixed in r10.

Title:	This construct is incorrectly recognized as a struct: void foo(struct bar* spam).
Status:	FIXED
Reported By:	Wawszczak, Jaros³aw
Reported On:	2001/08/30
Resolved By:	Joe Linoff
Resolved On:	2001/08/30

Id: 0033
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

This construct is incorrectly recognized as a struct: void foo(struct bar* spam).

Solution Description:

Fixed in r10.
This occurred because the parsing heuristic didn't recognize the the struct declaration was inside an argument list.

Title:	For -rpthpc only show packages.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/09/02
Resolved By:	Joe Linoff
Resolved On:	2001/09/04

Id: 0034
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

I have one more request.... I'd like the 'hierarchical contents' to show 'packages only', and not classes, namespaces, etc. Basically, I want to limit the depth to packages. The 'classes' link can still be the full glory. Without this, the current contents with classes is too detailed for the top-level index. With my mod, it will be a direct replacement of the old 'tree'.

I think that this is a good idea. I will release it in r11. Unfortunately, I won't be able to work on it until next week.

Solution Description:

Fixed in r11.

Title:	ccdoc 0.7a to 08 quick reference
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/09/02
Resolved By:	2001/09/04
Resolved On:	Joe Linoff

Id: 0035
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

I think that it would be useful to have a summary of the changes between 0.7a and 0.8 for users that are familiar with 0.7a.

I think that this is a good idea. I will add something as soon as I can.

Solution Description:

Fixed in r11.
Added a quick reference guide at the top level.

Title:	Comments get lost.
Status:	FIXED
Reported By:	Yuriy Stul
Reported On:	2001/09/03
Resolved By:	Joe Linoff
Resolved On:	2001/09/04

Id: 0036
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Comments get lost under the following conditions:
  /**
   * This is a dangling comment at the head of a file.
   */
  /**
   * This is a class comment that gets lost.
   */
  class A {};
You can work around this problem by changing the initial comment to a non-ccdoc style comment as follows:
  /*
   * This is a dangling comment at the head of a file.
   */
  /**
   * This is a class comment that gets lost.
   */
  class A {};

Solution Description:

Fixed in r12.
This problem occurred because the database reader assumed that comments could not exist in sequential records. The fix was in database.cc around line 399.

Title:	Change the asterisk column header to "Inherited From".
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/09/05
Resolved By:	Joe Linoff
Resolved On:	2001/09/05

Id: 0037
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Change the asterisk column header to "Inherited From". The asterisk is not very meaningful.

Solution Description:

Fixed in r13.

Title:	Change the Path column header to "Entity".
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/09/05
Resolved By:	Joe Linoff
Resolved On:	2001/09/05

Id: 0038
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Change the asterisk column header to "Inherited From". The asterisk is not very meaningful.

Solution Description:

Fixed in r13.

Title:	Performance problem in phase3.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/09/05
Resolved By:	Joe Linoff
Resolved On:	2001/09/07

Id: 0039
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The new version of ccdoc seems to generate HTML files much slower than v0.7a. In our tests it was running about 10X slower.

Solution Description:

Fixed in r14.
Found an O(N^2) complexity algorithm in databases::get_stmt_no_pkgs(). Converted the algorithm to O( n log(n) ). The test case performance improved from 49 minutes to 30 seconds but the real case is still slow.
Found another O(N^2) complexity algorithm in databases::get_stmt_no_pkgs() related to tree traversal for id lookups. Converted the algorithm to O( n log(n) ). The real test case performance improved from 18 hours to 12 minutes.
Made the generated HTML slightly more compact. The resulting output in the browers is identical.

Modified indenting to use <blockquote> and </blockquote> instead of <table><tr><td><    ></td><td> and </td></tr></table> because it saves characters and achieves the same result.
Removed extraneous carriage returns.
Removed the comment banner in the trailer.

Summary of performance improvements:

Added m_path_map and support to database.h.
Use m_path_map in phase3::html to improve performance.
Removed the redundant calculation of the previous link in phase3::html::write_class_details.
Improved phase2 performance as well.

Summary of other miscellanous changes:

Verbose mode because more verbose. It now reports each instance of each entity type for which HTML is created. In the past it only reported it for classes.
Removed the old, slow tree lookup code.

Title:	Protected inherited methods reported.
Status:	FIXED
Reported By:	John Rostykus
Reported On:	2001/09/05
Resolved By:	Joe Linoff
Resolved On:	2001/09/06

Id: 0040
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In some cases, it looks like protected inherited methods are reported.

Solution Description:

Fixed in r13.
The make_class_contents() method in phase3_html.cc was not verifying that the inherited methods were accessible.

Title:	Improve 0039 performance enhancement.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/09/07
Resolved By:	Joe Linoff
Resolved On:	2001/09/08

Id: 0041
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The following changes would improve the issue 0039 performance fix even more:

Use the same map for phase2 and phase3. In the current implementation, phase2 clears the map and phase3 re-creates it. This is unnecessary because they are the same.
Ignore comments. Although comments have ids, they are not used. This would reduce the memory footprint somewhat.
Don't write out the database if it hasn't changed. This occurs when phase3 is run independently.

Solution Description:

Fixed in r15.

Title:	ccdoc bug notification - not correctly determining variable name
Status:	FIXED
Reported By:	Paul Kohler
Reported On:	2001/09/10
Resolved By:	Joe Linoff
Resolved On:	2001/09/10

Id: 0042
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Version: ccdoc v0.8 r14 2001/09/07 bin_opt_msvc_MSWin32-4.0
Shell: cmd.exe
Platform: Windows 2000
It seems to be reporting a link and link text in the contents of a package as the value (it is a static global variable). There are two and the comments are generated correctly, but the link goes to the first one.
Here is the snippet of code with comments:
typedef int   Bool;
#define true  1
#define false 0

/**
 * Global boolean value to signal if an account is loaded.
 *
 * @author  Paul Kohler
 */
static Bool g_bAccountInit = false;

/**
 * Global boolean value to signal if the connection has been established.
 *
 * @author  Paul Kohler
 * @see IConnect
 */
static Bool g_bConnected = false;
And this is the resulting html snippit:
false(href="ccdoc.lib.libivr.false.var.html")   variable   public   Global
boolean value to signal if the ICSS connection has been established.
false(href="ccdoc.lib.libivr.false.var.html")   variable   public   Global
boolean value to signal if an account is loaded.
Excellent report! I was able to duplicate the problem in a few minutes and am currently working to fix it. My hope is that the fix will be released in r15 as early as today.

Solution Description:

Fixed in r15.
The variable parsing heuristic was not correctly recognizing '=' as an id separator in some cases. Look for "Issue 0042" in a comment in phase1_parser.cc.

Title:	Old hash mark syntax for @see does not work.
Status:	FIXED
Reported By:	Lou Sanchez-Chopitea
Reported On:	2001/09/10
Resolved By:	Joe Linoff
Resolved On:	2001/09/10

Id: 0043
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The old @see #foo syntax no longer works.

This was an oversight. I inadvertently deprecated it. It will be fixed in the next release.

Solution Description:

Fixed in r15.

Title:	The summary report could use a little more indenting.
Status:	FIXED
Reported By:	Lou Sanchez-Chopitea
Reported On:	2001/09/10
Resolved By:	Joe Linoff
Resolved On:	2001/09/10

Id: 0044
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

It would be nice to be able to control the indenting level for reporting hierarchical objects on the summary page..

Perhaps I could add a switch that would allow you to control the level of indenting.

Solution Description:

Fixed in r15.
Added the -rptcsi (Class Summary Indent) switch.

Title:	The variable width font in the Code: section is not as readable as the fixed width font used in 0.7a.
Status:	FIXED
Reported By:	Lou Sanchez-Chopitea
Reported On:	2001/09/10
Resolved By:	Joe Linoff
Resolved On:	2001/09/11

Id: 0045
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The variable width font in the Code: section is not as readable as the fixed width font used in 0.7a.
The mono-space font was removed because of a general consensus that the variable width font was easier to read as demonstrated by Bjarne Stroustroup changing the font for all C++ examples in his recent books.
I have no opinion one way or the other.
I will add a switch that allows the user to control this. of indenting.

Solution Description:

Fixed in r17.
Added the -rptfwcf (Fixed Width Code Font) switch.
I originally reported this as fixed in r15 but the generate HTML still seemed to be proportional so I changed the generated output.

Title:	The @see index doesn't seem to work.
Status:	FIXED
Reported By:	Chris Meuzelaar
Reported On:	2001/09/10
Resolved By:	Joe Linoff
Resolved On:	2001/09/10

Id: 0046
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

ccdoc fails to generate links for @see directives when generating documentation for a large number of files / classes when multiple instances of the function exist in a class (see below). The sample below will generate HTML with the link back to the first function CSampleTray::AddSampleAt 0, but not the other two. Attached are the batch files used to generate the documentation as well as the database file. I am generating documentation using ~500 files.

Here is a bit of sample code that doesn't work.
class A {
public:
  /**
   * Do stuff.
   * @see A::B 1
   * @see A::B 2
   */
  void B();
  void B(int);
  void B(double);
};

Solution Description:

Fixed in r16.
I thought that this bug was important enough to warrant a re-release.

Title:	The indenting on the contents page should be the same as the summary report.
Status:	FIXED
Reported By:	Lou Sanchez-Chopitea
Reported On:	2001/09/11
Resolved By:	Joe Linoff
Resolved On:	2001/09/11

Id: 0047
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The indenting on the contents page should be the same as the summary report.

Solution Description:

Fixed in r17.
Modified the -rptcsi (Class Summary Indent) switch to also change the contents indenting.

Title:	Derived classes in namespaces are not recognized correctly.
Status:	FIXED
Reported By:	Dmitry A.Steklenev
Reported On:	2001/09/11
Resolved By:	Joe Linoff
Resolved On:	2001/09/11

Id: 0048
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In the following example, the HTML for class_two does not correctly link to class_one.
namespace ccdoc_test {
  class class_one {
  };
  class class_two : public class_one {
  };
}

Solution Description:

Fixed in r17.
Partially scoped names were not being expanded in the extends clause processing in phase3_html.cc.

Title:	Non-template class method instantiation not recognized correctly.
Status:	FIXED
Reported By:	Dmitry A.Steklenev
Reported On:	2001/09/11
Resolved By:	Joe Linoff
Resolved On:	2003/02/17

Id: 0049
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In the following example, some_method() is reported as a separate function.
namespace ccdoc_test {
  class class_one {
  public:
    int some_method();
  };
  inline int class_one::some_method()
  {
    return 0;
  }
}
This is not quite as serious as the previous bug because it can be worked around as follows:
namespace ccdoc_test {
  class class_one {
  public:
    int some_method();
  };
  #if !defined( __ccdoc__ )
  inline int class_one::some_method()
  {
    return 0;
  }
  #endif
}

Solution Description:

Fixed in r33 and verified by test 69.
This was fixed as part of the issue 0149 work.

Title:	Ccdoc fails to parse methods with fct args properly.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/09/11
Resolved By:	Joe Linoff
Resolved On:	2001/09/11

Id: 0050
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The following example is reported incorrectly as a variable of name fp:
class A {
public:
  int fct2( void ( * fp ) ( ) ) ;
};

Solution Description:

Fixed in r17.
This bug resulted from the phase_parser not being able to correctly identify methods under certain conditions.

Title:	External class method implementations with default arguments are not correctly recognized.
Status:	FIXED
Reported By:	Lou Sanchez-Chopitea
Reported On:	2001/09/17
Resolved By:	Joe Linoff
Resolved On:	2003/02/17

Id: 0051
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

External class method implementations with default arguments are not correctly recognized. Here is an example:
class A {
public:
  void fct(int x=0);
};
void A::fct(int x)
{
}
Ccdoc treats the implementation as a separate function.
This occurs because ccdoc does not understand default arguments and thinks that the =0 makes two different argument sequences. You can workaround this in two different ways, both are shown below:
Workaround #1 Workaround #2
class A {
public:
  void fct(int x=0);
};
#if !defined(__ccdoc__)
void A::fct(int x)
{
}
#endif
class A {
public:
  void fct(int x /**@#-*/ =0 /**@#+*/ );
};

void A::fct(int x)
{
}
Because there are workarounds, this a low priority bug.

Solution Description:

Fixed in r33 and verified by test 69.
This was fixed as part of the issue 0149 work.

Title:	Backslash character definition ('\\') confuses the ccdoc scanner.
Status:	FIXED
Reported By:	Joe Linoff
Reported On:	2001/09/18
Resolved By:	Joe Linoff
Resolved On:	2001/09/18

Id: 0052
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The following definition confuses the ccdoc parser.
const char X = '\\';
This is a serious bug that will be fixed as soon as possible.

Solution Description:

Fixed in r18.
There was a scanner problem for detecting the ends of character constants in some cases.

Title:	No line numbers for internal comment parsing warnings.
Status:	FIXED
Reported By:	Ray Rizzuto
Reported On:	2001/09/18
Resolved By:	Joe Linoff
Resolved On:	2001/09/21

Id: 0053
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Error during parse of header file with a package comment:

WARNING: Internal comment parsing error.
 Unexpected EOF for ''.
 This comment will be ignored.
WARNING: Internal comment parsing error.
 Unexpected EOF for ''.
 This comment will be ignored.

Solution Description:

Fixed in r19.

Title:	Serious problem with typedef of struct
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:	Joe Linoff
Resolved On:	2001/09/21

Id: 0054
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

The following struct typedef conduses ccdoc.
typedef struct _TEST {
    int a;
    int b;
} TEST1;
It generates the following documentation:
package ccdocTest

Contents

    Entity    Type       Scope    Short Description
    a         typedef    public   undocumented
    b         variable   public   undocumented
This is definitely a bug. When I revisited the test suite I noticed that there were no cases for struct and class typedefs.
You might be able to workaround this problem as follows:
  struct _TEST {
    int a;
    int b;
  };
  typedef _TEST TEST1;

Solution Description:

Fixed in r19.
The ccdoc::phase1::parser::parse_typedef() method did not correctly recognize embedded structures.

Title:	ccdoc generates default special members for C style structs
Status:	CLOSED
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:	Joe Linoff
Resolved On:	2001/09/20

Id: 0055
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Ccdoc should never create default special members (constructor, destructor, operator=) for structs in C programs, since there is no such thing in C.
This is true. Unfortunately, ccdoc does not officially support C.
Perhaps this problem can be solved in another way by allowing you to specify -nocdsm in phase1 for certain files.

Solution Description:

Client has a workaround. I will re-open this issue if I get additional requests.

Title:	Incorrect line numbers reported in warning messages.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:	Joe Linoff
Resolved On:	2003/02/18

Id: 0056
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Try this:
---[ccdoctest.h]---
/** @pkg ccdocTest */

int x;
Ccdoc will say, that x is in ccdoctest.h:4, but it is in ccdoctest.h:3. It seems to me, that the extra 1 line number is related somehow to the ccdoc comment.

Solution Description:

Fixed in r34, verified by test 13.
This was extremely tricky because the line numbers were correct most of the time so it was hard to find a test case. The only time they were incorrect were when the first line of the file had a ccdoc directive that required a push/pop of the tokens that included the new line.

Title:	"Undocumented" as default short desc. in tables is confusing.
Status:	CLOSED
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:	Joe Linoff
Resolved On:	2001/09/21

Id: 0057
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

"Undocumented", the default short description can be confusing in HTML tables when most entries have a short description, since "Undocumented" entries can be easily overlooked. I think the solution is to give switch to override this text, then I can replace it with "-".

Solution Description:

Ccdoc already supports this. The resolution is described in detail in issue 0058.

Title:	Provide a way to turn off the default author and version for packages.
Status:	CLOSED
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:	Joe Linoff
Resolved On:	2001/09/21

Id: 0058
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

Reporting unascribed as the default package author and reporting version as unknown is not so useful in some projects, since we do it on package level. Perhaps -[no]rptdnpa and -[no]rptdnpd, where np is for non-package entity?

Solution Description:

Ccdoc provides a mechanism for turning off the default author and version for any package by allowing the client to specify them explicitly. The technique for doing this is to create a text file with entries for each property. That file could look something like this:
// Create empty entries for packages to avoid using the defaults.
/**
 * &nbsp;
 * @author &nbsp;
 * @version &nbsp;
 * @pkgdoc PKG1
 */
/**
 * &nbsp;
 * @author &nbsp;
 * @version &nbsp;
 * @pkgdoc PKG1::SUBPKG1
 */
/**
 * &nbsp;
 * @author &nbsp;
 * @version &nbsp;
 * @pkgdoc PKG1::SUBPKG2
 */
This file would be added to the phase 1 flow as follows:
ccdoc -db $CCDOC_DATABASE pkgdoc.txt

Title:	Validate ccdoc generated HTML.
Status:	FIXED
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:	Joe Linoff
Resolved On:	2001/09/20

Id: 0059
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

You can use the verifier at http://validator.w3.org to find errors in ccdoc generated output.
Thank you for a great suggestion! I never knew that an HTML verifier existed.

Solution Description:

Modified the ccdoc output to conform to the HTML 4.01 Transitional specification.

Title:	Group entries by type.
Status:	OPEN
Reported By:	Dékány Dániel
Reported On:	2001/09/20
Resolved By:
Resolved On:

Id: 0060
[Top]
[Summary]
[Next]
[Previous]

Problem Description:

In many situations it's very bad, that all entities are droped into one big list, you know, under the "Contents" tite, like this:
CONTENTS

Entry    Type Scope Shor Description
b    function ...
c    macro ...
d    function ...
e    package ...
f    macro ...
This would be much better in many cases:
CONTENTS


Packages

Entry    Type Scope Short Description
e    package ...


Functions

Entry    Type Scope Short Description
b    function ...
d    function ...


Macros

Entry    Type Scope Short Description
c    macro ...
f    macro ...
A switch like -[no]grpbytype? I don't hink so, cos it's not enough generic (E.g. maybe an alphabetical index is required too). I think the real solution is to allow user to specify any number of tables, with custom grouping and title. Something like this:
$ ccdoc ...  -table(type) "Contents" -table() "Index" ...
(Note that I have skipped unimportant parts with ellipsis)
It would generate two tables: one with title "Contents" and with grouping by entity type, and below another table with title "Index" without grouping (just an alphabetiacal index, like the table in the current version). I put the grouping condition into parenthesis to allow multi-level grouping for future developmens, like -contents(type,functionality).
This is an interesting suggestion. The previous version of ccdoc did use to group by entity. I will revisit that decision.

Solution Description:

Title:	Typedef struct statement does not include struct comments.
Status:	OPEN
Reported By:	Dékány Dániel
Reported On:	2001/09/23
Resolved By:
Resolved On:

Id: 0061
[T