ccdoc home page
Ccdoc Issues

CLOSED Status
All
Joe Linoff
$Date: 2004/09/30 16:09:26 $
$Revision: 1.33 $

Entry Summary
Id Title Status
0011 Instantiations of class template methods are reported as global functions. CLOSED
0023 DOC++ vs ccdoc CLOSED
0055 ccdoc generates default special members for C style structs CLOSED
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
0065 Links from documentation in namespaces are not recognized correctly. CLOSED
0081 Multi-space blank lines between SHORT and LONG descriptions cause them to merge. CLOSED
0100 If using switch -files with a wildcard expression the first file is not processed. CLOSED

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]
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: 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: 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: "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: Links from documentation in namespaces are not recognized correctly.
Status: CLOSED
Reported By: Dmitry A.Steklenev
Reported On: 2001/09/25
Resolved By: Joe Linoff
Resolved On: 2001/09/25
Id: 0065
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Code Sample:
namespace nms  {

  class some_class
  {
     public:
       void some_class();
  };

  /** 
   * Some description
   * 
   * Red, but not linked:
   * @$ some_class
   * and "see also" have same problem.
   * @see some_class
   */
  
  class some_other_class
  {
     public:
       void some_other_class();
  };
}
Solution Description:
Ccdoc does not resolve scoped identifiers (because it does not process included header files that may contain "using" statements). This means that the user must be explicitly specify the full scope of an identifier as shown below.
namespace nms  {

  class some_class
  {
     public:
       void some_class();
  };

  /** 
   * Some description
   * 
   * Red, but not linked:
   * @$ nms::some_class
   * and "see also" have same problem.
   * @see nms::some_class
   */
  
  class some_other_class
  {
     public:
       void some_other_class();
  };
}

I added fix that will resolve partially scoped references in most cases. See issue 0118 for details.


Title: Multi-space blank lines between SHORT and LONG descriptions cause them to merge.
Status: CLOSED
Reported By: Ben Zoe
Reported On: 2001/10/23
Resolved By: Joe Linoff
Resolved On: 2001/10/24
Id: 0081
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Multi-space blank lines between SHORT and LONG descriptions cause them to merge.
Solution Description:
The current ccdoc behavior is correct. Blanks are used to indicates lines in HTML <pre> clauses. The fix that was described (testing for lines that contain w/s) would fail to properly parse the following case:
/**
 * This is a short description with some code in it:
 * 
 * // Whitespace test
 * 
 * 
* * This is the start of the long description. */

I am not sure that this resolution is correct because the ccdoc short description does not conform to the javadoc specification. See issue 0089 for details.


Title: If using switch -files with a wildcard expression the first file is not processed.
Status: CLOSED
Reported By: Mĺrten Gustavsson
Reported On: 2001/11/09
Resolved By: Joe Linoff
Resolved On: 2001/11/12
Id: 0100
[Top]
[Summary]
[Previous]
Problem Description:
I saw in the issue list that someone has a problem with gnuwin32. If using switch -files with a wildcard expression the first file is not processed. No problem if removing the -files switch.
Solution Description:
The first file is not really ignored because the ccdoc expects it to contain a list of files to process. When it doesn't find any files it goes on to the other entries on the command line.

[Top]
This page is maintained by Joe Linoff.
Last updated: $Date: 2004/09/30 16:09:26 $

This page was automatically generated by issues.pl.