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 |
|
Id: 0060
[Top] [Summary] [Next] |
In many situations it's very bad, that all entities are droped into one big list, you know, under the "Contents" tite, like this:Solution Description:This would be much better in many cases:CONTENTS Entry Type Scope Shor Description b function ... c macro ... d function ... e package ... f macro ...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:
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).$ ccdoc ... -table(type) "Contents" -table() "Index" ... (Note that I have skipped unimportant parts with ellipsis)
This is an interesting suggestion. The previous version of ccdoc did use to group by entity. I will revisit that decision.
|
Id: 0061
[Top] [Summary] [Next] [Previous] |
The fix for issue 0054 only recognizes ccdoc style comments for the typedef, not for the structure.Solution Description:
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.
|
Id: 0062
[Top] [Summary] [Next] [Previous] |
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.Solution 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*' ' + '<a href="' + relpath + '">\\' (two backslash in the HTML output, not C escaping of one backslash...))
|
Id: 0067
[Top] [Summary] [Next] [Previous] |
Code Sample:Solution Description: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 {};
|
Id: 0093
[Top] [Summary] [Next] [Previous] |
Javadoc has quite an advanced feature for doc comment inheritance, see http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javadoc.html#inheritingcomments.Solution Description: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.
|
Id: 0094
[Top] [Summary] [Next] [Previous] |
Previously I suggested that you implement doc comment inheritance. If you decide to do so I have another suggestion.Solution Description: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:
Theses classes will internally be represented as something like this: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 Derivedclass 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.
|
Id: 0096
[Top] [Summary] [Next] [Previous] |
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:Solution Description: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.
|
Id: 0105
[Top] [Summary] [Next] [Previous] |
The javadoc @see tag defines the label part as optional: http://java.sun.com/j2se/1.4/docs/tooldocs/win32/javadoc.html#@seeSolution Description: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.
|
Id: 0106
[Top] [Summary] [Next] [Previous] |
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#seesearchorderSolution Description: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.
|
Id: 0108
[Top] [Summary] [Next] [Previous] |
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.Solution Description: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"
- -rptdefsd, documentation error, the default text is "undocumented", not "automatically generated". Documentation is exactly as for switch -rptdefasd, did you forget to edit after copy?
- -rptdefv, this switch sets the default text for missing version information, documentation says something completely different. Default text is "unknown", not "undocumented"
And some suggestions:
- The generated documentation has only one little problem, undocumented packages are reported "Implicitly defined" on the index pages. I suggest that you use the switch -rptdefsd instead of -rptdefasd for missing package documentation.
- In order to find all possible problems with the documentation, mark the text red
|
Id: 0113
[Top] [Summary] [Next] [Previous] |
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.Solution Description:
I think that this is very interesting idea that shouldn't be too difficult. I will look into it for the next release.
|
Id: 0119
[Top] [Summary] [Next] [Previous] |
In regards to issue 0115, replacing the backslashes with forward slashes in the -html switch does fix the problem. i.e. this worksSolution Description:But in DOS you can't use backslashes in the headers path. i.e. this doesn't workccdoc -db docs.db -html ./doc ..\Headers\*.hThis 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.ccdoc -db docs.db -html ./doc ../Headers/*.h
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.
|
Id: 0121
[Top] [Summary] [Next] [Previous] |
I use package names that reflect the directory structure. Each package is run through ccdoc in a separate ccdoc invocation.Solution Description: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.
|
Id: 0126
[Top] [Summary] [Next] [Previous] |
CcDoc does not recognize ccdoc c++ short comment in a "typedef struct" definition (comment does not appear).Solution Description:typedef struct { int foo1; //@- useful stuff 1 int foo2; //@- useful stuff 2 } MY_STRUCT;
|
Id: 0128
[Top] [Summary] [Next] [Previous] |
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).Solution Description:
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.
|
Id: 0131
[Top] [Summary] [Next] [Previous] |
I can't report this verbatim because my e-mail system crashed but here is my best recollection.Solution Description: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";
|
Id: 0132
[Top] [Summary] [Next] [Previous] |
Solution Description:Presently we have
string m_memberString; //@- the member documentation for this itemHow 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;
|
Id: 0137
[Top] [Summary] [Next] [Previous] |
The {@link} directive is not correctly recognized in @param clauses. The code example below demonstrates the problem:Solution Description: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); }; };
|
Id: 0143
[Top] [Summary] [Next] [Previous] |
"Javadoc documentation is great and very handy to use".Solution Description:
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).
|
Id: 0148
[Top] [Summary] [Next] [Previous] |
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?Solution Description:
I have not thought about it because I don't know much about style sheets but it sounds like a good idea.
|
Id: 0151
[Top] [Summary] [Next] [Previous] |
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!Solution Description:The file (simple ex.) could have key-string pairs:
Then you could generate english documentation: ccdoc -langfile ccdoc.en.language ... and finnish: ccdoc -langfile ccdoc.fi.language ...file: ccdoc.en.language CLASS=class DESTRUCTOR=destructor file: ccdoc.fi.language CLASS=luokka DESTRUCTOR=tuhoaja
|
Id: 0165
[Top] [Summary] [Next] [Previous] |
Doxygen allows a virtual grouping of definitions that is very useful (@name and @{).Solution Description:
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.
|
Id: 0167
[Top] [Summary] [Previous] |
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:Solution Description:--> 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"
Fixed in r39, verified by test 84.The short description string size was not updated properly in ccdoc::phase1::scanner_doc::add_line.