ccdoc home page
Ccdoc Issues

OPEN Status
All
Joe Linoff
$Date: 2003/05/15 17:22:47 $
$Revision: 1.31 $

Entry Summary
Id Title Status
0060 Group entries by type. OPEN
0061 Typedef struct statement does not include struct comments. OPEN
0062 Long entry name deforms HTML table. OPEN
0067 Ccdoc does not correctly reset the access specifiers for methods in base classes that are derived as protected or private. OPEN
0093 Add javadoc style doc comment inheritance. OPEN
0094 Comment reuse for overloaded functions. OPEN
0096 Provide an @repeat operator to avoid having to re-type comments. OPEN
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
0108 -rptdefasd, -rptdefsd and -rptdefv problems and suggestions OPEN
0113 Merge separate ccdoc databases. OPEN
0119 Inconsistent command line syntax for -html paths under DOS. OPEN
0121 Reuse namespace comments between packages. OPEN
0126 CcDoc does not recognize ccdoc c++ short comment in a "typedef struct" definition. OPEN
0128 Order class entities the same way that were ordered in v07. OPEN
0131 Support comma separated declarations. OPEN
0132 support single-line prefix comments via //@+ OPEN
0137 The {@link} directive does not work @param clauses. OPEN
0143 Support javadocs frames format. OPEN
0148 Allow users to customize ccdoc output using a CSS file. OPEN
0151 Translate the generated html to other languages. OPEN
0165 Doxygen compatibility - support virtual grouping of definitions. OPEN
0167 In German we want to use embedded dots in the short description. OPEN

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]
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
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
The fix for issue 0054 only recognizes ccdoc style comments for the typedef, not for the structure.
This occurs because ccdoc only associates comments with statements.

In this case there is only one statement but it is clear that it could be broken into the struct definition and the typedef. It might be possible to modify ccdoc with a heuristic that recognizes this construct and breaks it into two.

This is a low priority enhancement because this syntax is C artifact that is not necessary in C++ because the struct [name] declares [name] as a type.

Solution Description:

Title: Long entry name deforms HTML table.
Status: OPEN
Reported By: Dékány Dániel
Reported On: 2001/09/23
Resolved By:
Resolved On:
Id: 0062
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Just an idea: Long entry name stretches the first column too much. In the worst case it makes the "Contents" table unusable, since it stretches the first column so much that there will be no sufficient space for the short description.

A possible solution is to give a switch to specify the maximum entry name length, then break long names into two (or three, etc...) with an "\\<br>\\" in the HTML (to be more precise, with '\\</a><br>' + indent*'&nbsp;' + '<a href="' + relpath + '">\\' (two backslash in the HTML output, not C escaping of one backslash...))

Solution Description:

Title: Ccdoc does not correctly reset the access specifiers for methods in base classes that are derived as protected or private.
Status: OPEN
Reported By: Dmitry A.Steklenev
Reported On: 2001/10/01
Resolved By:
Resolved On:
Id: 0067
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Code Sample:
  class some_base_class
  {
     public:
       /** Must be reported as "protected" in some_class_01 and
         * as "private" in some_class_02, but reported as "public" */
       void some_public_method();
     protected:
       /** Must be reported as "protected" in some_class_01 and
         * as "private" in some_class_02, but reported as "protected" */
       void some_protected_method();
  };

  class some_class_01 : protected some_base_class {};
  class some_class_02 : private some_base_class   {};

Ccdoc always reports methods as they appear in the original class specification and expects the user to understand how the access-specification changes if protected or private inheritance is used.

This may be difficult for many users. I will look into changing this behavior or making it optional via a switch. Meanwhile, if you don't want the users to see the methods, you can work around this as follows:

  class some_base_class
  {
     public:
       /** Must be reported as "protected" in some_class_01 and
         * as "private" in some_class_02, but reported as "public" */
       void some_public_method();
     protected:
       /** Must be reported as "protected" in some_class_01 and
         * as "private" in some_class_02, but reported as "protected" */
       void some_protected_method();
  };

  class some_class_01
#if !defined(__ccdoc__)
   : protected some_base_class
#endif
    {};
  class some_class_02
#if !defined(__ccdoc__)
   : private some_base_class
#endif
    {};
Solution Description:

Title: Add javadoc style doc comment inheritance.
Status: OPEN
Reported By: Mĺrten Gustavsson
Reported On: 2001/11/01
Resolved By:
Resolved On:
Id: 0093
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Javadoc has quite an advanced feature for doc comment inheritance, see http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javadoc.html#inheritingcomments.

I would very much appreciate doc comment inheritance, prefferably according to javadoc 1.4. Javadoc 1.3 (http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html#inheritingcomments) is not so advanced but would be quite useful also.


This is an excellent idea. I will look into how feasible it is for ccdoc. The only issue is how well ccdoc can recognize these relationships.
Solution Description:

Title: Comment reuse for overloaded functions.
Status: OPEN
Reported By: Mĺrten Gustavsson
Reported On: 2001/11/01
Resolved By:
Resolved On:
Id: 0094
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Previously I suggested that you implement doc comment inheritance. If you decide to do so I have another suggestion.

I believe that the javadoc rules says that a method must override a method in the ancestor class to reuse a doc comment. Doc comments cannot be reused for constructors, destructors etc.

I find it quite tedious to write doc comments for constructors and destructors. It would save a lot of typing if one could reuse doc comments beween them.

I can see that the implementation can be difficult, but there is another enhancement that could simplify a lot. Lets call it doc comment reuse of overloaded functions. There is no such thing in javadoc, but maybe there should be. I have read the javadoc spec over and over since I really believed there was such a rule, but there is no rule.

Doc comment reuse of overloaded functions

If an overloaded member function does not have a doc comment, and placed after a function it overloads, it will inherit the doc comment of that function. The names of the parameters of the overloaded functions must be same, only types may vary.

The result is that one only needs to document the first function in a group of overloaded functions.

Doc comment reuse of constuctors etc

Hope that you will excuse me doing specification by example: If a member function (constructor, destructor, etc) uses the class name itself in the parameter list, a second "invisible" function is generated, replacing the current class name with a superficial "this". Using the superficial type "this" is good because it is a reserved word in C++ preventing any real class to be defined.

If the original function has a doc comment the generated function will be placed after the original one, inheriting its doc comment using the rule for overloaded functions.

If the original function doesn't have a doc comment, the generated one will be placed before the original one, allowing the original one to inherit from the generated one using the rule for overloaded functions.

A code example:

class Base 
{ 
        /** Default construcor */ 
        Base(); 
        /** 
         * Copy constructor. 
         * 
         * @param src   is the object to copy from 
         */ 
        Base(const Base &src); 
        /** Destructor */ 
        ~Base(); 
        /** 
         * Assignment operator. 
         * 
         * @param src   is the object to copy from 
         * @return              a const reference to this object 
         */ 
        const Base& operator=(const Base& src); 
} // class Base 

class Derived : public Base 
{ 
        Derived(); // inherit doc comment 
        Derived(const Derived &src); // inherit doc comment 
        ~Derived(); // inherit doc comment 
        const Derived& operator=(const Derived & src); // inherit doc comment 
        /** 
         * Strange copy constructor that slices the object. 
         * 
         * @param src   is the base class object to copy from 
         */ 
        Derived(const Base &src); 
} // class Derived 
Theses classes will internally be represented as something like this:
class Base 
{ 
        /** Default construcor */ 
        Base(); 
        this(); // inherit doc comment from previous using overload rule 
        /** 
         * Copy constructor. 
         * 
         * @param src   is the object to copy from 
         */ 
        Base(const Base &src); 
        this(const this &src);// inherit doc comment from previous using overload rule 
        /** Destructor */ 
        ~Base(); 
        ~this();// inherit doc comment from previous using overload rule 
        /** 
         * Assignment operator. 
         * 
         * @param src   is the object to copy from 
         * @return              a const reference to this object 
         */ 
        const Base& operator=(const Base& src); 
        const this& operator=(const this& src);// inherit doc comment from previous using overload rule 
} // class Base 

class Derived : public Base 
{ 
        this(const this &src); // this one will pick up doc comment from base class 
        Derived(); // inherit doc comment from previous using overload rule 
        this(const this &src); // this one will pick up doc comment from base class 
        Derived(const Derived &src); // inherit doc comment from previous using overload rule 
        ~this(); // this one will pick up doc comment from base class 
        ~Derived(); // inherit doc comment from previous using overload rule 
        const this& operator=(const this& src); // this one will pick up doc comment from base class 
        const Derived& operator=(const Derived & src); // inherit doc comment from previous using overload rule 
        /** 
         * Strange copy constructor that slices the object. 
         * 
         * @param src   is the base class object to copy from 
         */ 
        Derived(const Base &src); 
} // class Derived 

I really like this idea. I will look into how feasible it is for ccdoc. The only issue is how well ccdoc can recognize these relationships.
Solution Description:

Title: Provide an @repeat operator to avoid having to re-type comments.
Status: OPEN
Reported By: David McBride
Reported On: 2001/11/02
Resolved By:
Resolved On:
Id: 0096
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
As you know, if you have a set of overloaded functions, they often perform essentially the same function, and could be described by the same ccdoc comment. Therefore, it would be handy to have a tag that would tell ccdoc to apply the comment attached to the previous method to the current method. For example:
class MyClass {
public:
     /**
     * Performs some useful function. blah blah blah.
     * Some long, involved explanation that I don't
     * want to repeat over and over again.
     * @param someVar Some user defined variable.
     * @returns Returns 0 if successful or not 0 otherwise.
     */
     void myOverloadedFunct(A* someVar);

     /**
     @repeat
     */
     void myOverloadedFunct(B* someVar);

     /**
     @repeat
     */
     void myOverloadedFunct(C* someVar);

     /**
     @repeat
     */
     void myOverloadedFunct(D* someVar);

     /**
     @repeat
     */
     void myOverloadedFunct(E* someVar);
}

This is an interesting suggestion. I believe that it relates to issues 0093 and 0094. They are all trying to address the problem of having to type redundant comments. I am actively looking into this.
Solution Description:

Title: The javadoc @see tag defines the label part as optional.
Status: OPEN
Reported By: Mĺrten Gustavsson
Reported On: 2001/11/08
Resolved By:
Resolved On:
Id: 0105
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
The javadoc @see tag defines the label part as optional: http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javadoc.html#@see

If you decide to do the label optional, javadoc specifies how to generate the link: http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javadoc.html#shortened

I don´t feel that this improvement is very important, but if you like the idea put it on the issue list and maybe implement it if there is time and no more important things to do.

Solution Description:

Title: The javadoc spec for @see allows unqualified names as well as qualified names.
Status: OPEN
Reported By: Mĺrten Gustavsson
Reported On: 2001/11/08
Resolved By:
Resolved On:
Id: 0106
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
The javadoc spec for @see allows unqualified names as well as qualified names: http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javadoc.html#seesearchorder

I believe that ccdoc requires a fully qualified c++ class name if the reference is to another class. The javadoc spec relies on rules including the java compiler and I don´t believe that following their search patterns will add that much.

However, it would be nice if the @see tag accepts valid c++ class names. Leaving out the namespace part if the referencing class belongs to the same namespace as the referenced class would be an improvement.

I don´t think this improvement is very important since namespaces are quite short compared to java packages.

Solution Description:

Title: -rptdefasd, -rptdefsd and -rptdefv problems and suggestions
Status: OPEN
Reported By: Mĺrten Gustavsson
Reported On: 2001/11/08
Resolved By:
Resolved On:
Id: 0108
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
I am playing around with the switches -rptdefasd, -rptdefsd and -rptdefv, the intention to mark the text red "Undocumented" in order to find missing documentation and implicitly defined member funcions.

For the implicitly defined member funcions I want the text "Implicitly defined", and for things that I forgot to document "Undocumented", the switches used:

-rptdefasd "Implicitly defined" -rptdefsd "Undocumented" This causes the class documentation look just like I want. However, I have found the following errors:

The switches I am quite happy with: -rptdefa "Unascribed" -rptdefasd "Implicitly defined" -rptdefsd "Undocumented" -rptdefv "Unknown"

And some suggestions:

Solution Description:

Title: Merge separate ccdoc databases.
Status: OPEN
Reported By: John Rostykus
Reported On: 2001/11/20
Resolved By:
Resolved On:
Id: 0113
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
On a related note, I would like to talk to you about possibly supporting a feature in ccdoc to merge databases. We could really parallelize the process if we were not limited to having every ccdoc process write to the same database. For example, run the header processing on each of the 50 or so subsystems individually in parallel, run a (new) step to merge the resulting databases into 1, and then do the index/html steps. Does ccdoc have any capability like this? If not, what do you think of this idea? In general, long processes that are single threaded are what kill our build times, and ccdoc (the way we use it) at ~1 hour is in that camp.
I think that this is very interesting idea that shouldn't be too difficult. I will look into it for the next release.
Solution Description:

Title: Inconsistent command line syntax for -html paths under DOS.
Status: OPEN
Reported By: Richard Cooper
Reported On: 2001/11/27
Resolved By:
Resolved On:
Id: 0119
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
In regards to issue 0115, replacing the backslashes with forward slashes in the -html switch does fix the problem. i.e. this works
ccdoc -db docs.db -html ./doc ..\Headers\*.h
But in DOS you can't use backslashes in the headers path. i.e. this doesn't work
ccdoc -db docs.db -html ./doc ../Headers/*.h
This is not entirely satisfactory because now the two path descriptions in the command line need to be in different formats (the html path in UNIX form, the header path in DOS form). IMO the best fix would be to accept any paths in either format on any platform, but I have no idea how tricky that would be to implement.
I agree.

Unfortunately this is somewhat difficult because ccdoc can't reliably determine whether it is running under cmd.exe or under a unix shell that is running on top of cmd.exe at run time.

If it is running under cmd.exe, it can safely replace backslashes with forward slashes but, if it is running under a unix shell that is running on top of cmd.exe it cannot.

I will look into whether ccdoc can be enhanced to allow you to specify UNIX style paths (with wildcards) under DOS.

Solution Description:

Title: Reuse namespace comments between packages.
Status: OPEN
Reported By: Gustavsson Mĺrten
Reported On: 2001/11/29
Resolved By:
Resolved On:
Id: 0121
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
I use package names that reflect the directory structure. Each package is run through ccdoc in a separate ccdoc invocation.

I use the same namespace between packages.

The namespace comment is valid only for the package in which it is defined. This is alright. The problem is that the documentation is a bit unclear about the scope for namespace doc comment reuse. I thought the namespace comment could be reused between packages.


This makes good sense. In fact, this is how it should work. I suspect that there is a bug in there somewhere.
Solution Description:

Title: CcDoc does not recognize ccdoc c++ short comment in a "typedef struct" definition.
Status: OPEN
Reported By: Luis Menina
Reported On: 2002/02/26
Resolved By:
Resolved On:
Id: 0126
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
CcDoc does not recognize ccdoc c++ short comment in a "typedef struct" definition (comment does not appear).
typedef struct 
{ 
    int foo1; //@- useful stuff 1
    int foo2;   //@- useful stuff 2
} MY_STRUCT;
Solution Description:

Title: Order class entities the same way that were ordered in v07.
Status: OPEN
Reported By: Luis Menina
Reported On: 2002/03/01
Resolved By:
Resolved On:
Id: 0128
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
May the class content be sorted not just alphabetically, but separating method and attributes ? I think it would be more clear and efficient (as it was in ccdoc v0.7).
Some folks like it this way, others like it the way that you have described. I think that a switch should be added that allows this.
Solution Description:

Title: Support comma separated declarations.
Status: OPEN
Reported By: Esmond Pitt
Reported On: 2002/09/24
Resolved By:
Resolved On:
Id: 0131
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
I can't report this verbatim because my e-mail system crashed but here is my best recollection.

Modify ccdoc to allow different comments for each item in a comma separated declaration. For example:

   const string
      /** This is one string */
      string1 = "aaa",
      /** This is another string */
      string2 = "bbb";
Note that you can workaround this in the near term as follows:
   // Workaround
   /** This is one string */
   const string string1 = "aaa";
   //** This is another string */
   const string string2 = "bbb";
Solution Description:

Title: support single-line prefix comments via //@+
Status: OPEN
Reported By: Esmond Pitt
Reported On: 2002/09/24
Resolved By:
Resolved On:
Id: 0132
[Top]
[Summary]
[Next]
[Previous]
Problem Description:

Presently we have

        string  m_memberString; //@- the member documentation for this item
How about adding this:
        //@+ the member documentation for this item
        string  m_memberString;

This makes sense as a shorthand but since you can workaround it by using the following syntax. This modification will be scheduled with a lower priority.
        /** the member documentation for this item */
        string  m_memberString;
Solution Description:

Title: The {@link} directive does not work @param clauses.
Status: OPEN
Reported By: Joe Linoff
Reported On: 2002/12/06
Resolved By:
Resolved On:
Id: 0137
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
The {@link} directive is not correctly recognized in @param clauses. The code example below demonstrates the problem:
namespace testXX {
   class A {
   public:
      A();
      ~A();
      /**
       * Run the test using the specified arguments.
       * @param argc The number of arguments.
       * @param argv The collection of arguments.
       * @returns The run status.
       */
      virtual int Run(int argc,char** argv);
   };
   class test : public A {
   public:
      test();
      ~test();
      /**
       * Run the test using the {@link test99::A::Run} command.
       * @param argc The number of arguments {@link test99::A::Run}.
       * @param argv The collection of arguments {@link test99::A::Run}.
       * @returns The run status {@link test99::A::Run}.
       */
      virtual int Run(int argc,char** argv);
   };
};

2002/12/06 jdl
After a bit more investigation, I found that there was a workaround as shown below which makes the fix less urgent.
namespace testXX {
   class A {
   public:
      A();
      ~A();
      /**
       * Run the test using the specified arguments.
       * @param argc The number of arguments.
       * @param argv The collection of arguments.
       * @returns The run status.
       */
      virtual int Run(int argc,char** argv);
   };
   class test : public A {
   public:
      test();
      ~test();
      /**
       * Run the test using the {@link test99::A::Run} command.
       * @param argc The number of arguments 
       *             {@link test99::A::Run}.
       * @param argv The collection of arguments
       *             {@link test99::A::Run}.
       * @returns The run status {@link test99::A::Run}.
       */
      virtual int Run(int argc,char** argv);
   };
};
Solution Description:

Title: Support javadocs frames format.
Status: OPEN
Reported By: Thomas Bednarz
Reported On: 2003/01/24
Resolved By:
Resolved On:
Id: 0143
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
"Javadoc documentation is great and very handy to use".
I agree. I will look into this in the near future. A couple of additional thoughts: 1) the new format should be switch controllable to avoid disrupting existing clients, 2) the new format may be higher priority than the XML release (this needs to be investigated).
Solution Description:

Title: Allow users to customize ccdoc output using a CSS file.
Status: OPEN
Reported By: Sakari Forsberg
Reported On: 2003/02/10
Resolved By:
Resolved On:
Id: 0148
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Have you thought, instead of giving color parameters etc. to ccdoc that it can make custom looking html you could give a custom tailored .css-file to ccdoc and it could generate html which uses a .css-file?
I have not thought about it because I don't know much about style sheets but it sounds like a good idea.
Solution Description:

Title: Translate the generated html to other languages.
Status: OPEN
Reported By: Sakari Forsberg
Reported On: 2003/02/14
Resolved By:
Resolved On:
Id: 0151
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Have you thought adding a change to translate contents of generated html? It would be nice, if ccdoc would read certain words like "class", "contents" etc. from a file which would be kind of resource file. If you change contents a file to f. ex. finnish, then you would have finnish documentation!

The file (simple ex.) could have key-string pairs:

file: ccdoc.en.language
  CLASS=class
  DESTRUCTOR=destructor

file: ccdoc.fi.language
 CLASS=luokka
 DESTRUCTOR=tuhoaja
Then you could generate english documentation: ccdoc -langfile ccdoc.en.language ... and finnish: ccdoc -langfile ccdoc.fi.language ...
Solution Description:

Title: Doxygen compatibility - support virtual grouping of definitions.
Status: OPEN
Reported By: Richard Durwim
Reported On: 2003/02/21
Resolved By:
Resolved On:
Id: 0165
[Top]
[Summary]
[Next]
[Previous]
Problem Description:
Doxygen allows a virtual grouping of definitions that is very useful (@name and @{).
I am all in favor of making ccdoc and doxygen style comments compatible so that users can use both of them. This change is a challenge because the syntax conflicts with a current ccdoc usage. I will look into it when I can.
Solution Description:

Title: In German we want to use embedded dots in the short description.
Status: OPEN
Reported By: Christian Ehrlicher
Reported On: 2003/02/25
Resolved By:
Resolved On:
Id: 0167
[Top]
[Summary]
[Previous]
Problem Description:
I've found: another little problem. In German we write for the short form of "for example" "z.B.". ccdoc ignores silently the rest of the line after the B:

--> in .h : /** das ist z.B. test */
--> in .html : "das ist z.B" without the last point an the rest of the line


Your example should work. This is a bug in ccdoc. It is supposed to terminate the short description after it encounters a dot that is followed by white space.

For now you can workaround it by embedding trailing spaces before the last dot as shown below:

--> in .h : /** das ist z.B . test */
--> in .html : "das ist z.B. test"

Solution Description:
Fixed in r39, verified by test 84.

The short description string size was not updated properly in ccdoc::phase1::scanner_doc::add_line.


[Top]
This page is maintained by Joe Linoff.
Last updated: $Date: 2003/05/15 17:22:47 $

This page was automatically generated by issues.pl.