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.

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.

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...))

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
    {};

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.

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.

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.

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.

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.

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:

• -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"

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

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

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.

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.

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.

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;

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.

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";

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;

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);
   };
};

"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).

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.

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 ...

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.

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"

Fixed in r39, verified by test 84.

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

Several users have requested a search capability in ccdoc. This capability can be provided in two ways: use a standard HTML based search engine on the generated files or provide a database of indexed items that can be used for a custom search engine. Although the standard HTML based search engine approach works well, there are still some users who would like a pre-generated index of searchable items.

My current thinking about how to implement this is to provide a -rptidx switch for phase 3 that generates two HTML indices: one by name and one by entity type by name.

It would also generate an XML based index file that could be used by 3rd party search engines. Each XML record would contain the name of the entry (i.e. GetName), the type (method, function, etc.) and the associated URL. Multiple entries with the same name would be allowed.

It might also be desirable to have it contain information about the scope of the name. This means that each enclosing namespace and class might be specified as list. Consider the case of the X::Y::A::B::GetName() method where X and Y are namespaces, and B is a nested class inside of A. The scope information would contain data like ((nsp X) (nsp Y) (cls A) (cls B)).

Yet another desirable attribute would be to have this index view of the data tie in to the XML output that is being generated in the proto-type version for the next major release. In this release the database format will convert to XML. The phase 2 processing will generate fully cross-indexed entities that are used in phase 3 to generate HTML. Of course the user can stop at phase 2 and work directly with the XML. This is different than today where the database format is NOT XML and it is not fully cross referenced.

This suggestion was actually made some time ago but I just got around to adding it.

Ragav suggested that ccdoc be enhanced to support quick links to entries in the table of contents. The idea is that for tables with a large number of classes (or methods), the user could click on a quick link to the region they were interested in.

In practice it would look something like this:

Table Of Contents

Quick Links: A B C D E F G H ... Z

.
.
.

I think that this would be very useful for large systems that have hundreds or even thousands of classes.

I have found something wrong with my output though - not sure if this is a bug or if I am doing something wrong. I have the following (simplified) situation:

class SOMECLASS
{
public:
    void  DoSomething(int x);
    int x;
};

You'll see that I have a member variable 'x' and also a member function which has 'x' in it's argument list. This causes CcDoc to place a link from the argument name 'x' to the documentation for the member variable 'x'.

I could simply change one of these names to ensure that there is no clash, however I thought you'd like this kind of problem submitted as a bug.

I have a file as_config.h:

#ifndef AS_CONFIG_H
#define AS_CONFIG_H

namespace ApplicationInterface
{
   enum 
      {  zero=0,
         one=1,
         two=2
      };
   enum {
      number_of_tasks         = 60,
      task_stack_size         = 4096,
      number_of_queues        = 32,
      number_of_event_groups  = 32,
      number_of_timers        = 32
   };
   
} // namespace ApplicationInterface

#endif

The problem is that I see two "$anonymous$" enum entities in the namespace page, but both link only to a page that lists only the first enum.

I know that in this case the enums could be combined, but this seems less than satisfactory as a general solution. Is this a known issue? (I couldn't find one that seemed to match on the ccdoc website) Is there interest in fixing this? I have no idea how hard it is to change this. Either way I likely will have to do something to at least address this in-house.(perhaps just complain when the second enum is detected...this would at least allow us to detect the problem and perhaps "invent" a name for at least one of them).

It would be nice if ccdoc had a directive like "@entity <entityName>".

Here is how I would want to use it. I have a macro which declares and defines a static member function. It is a macro because every class in the hierarchy should have this function (it returns an "interface ID"). The code currently looks like this:

  //@{
  // Returns the ID value for this interface.
  //@}
  Gf_DECL_INTERFACE_ID("{8DC3F1C6-F7CA-42d8-AFD6-7AF950C5C11E}")
# if defined(__ccdoc__)
  static Gf_GUID InterfaceID();
# endif

It would be nicer if I could write:

  //@{
  // Returns the ID value for this interface.
  // @entity static Gf_GUID InterfaceID()
  //@}
  Gf_DECL_INTERFACE_ID("{8DC3F1C6-F7CA-42d8-AFD6-7AF950C5C11E}")

If there is already a way to do this, I'd appreciate hearing about it. If not, please consider adding a feature of this sort sometime in the future.

---

I can see where it would be useful to have real function name in the table of contents. The #ifdef workaround will certainly work until this issue is addressed.

I've been happily using CCDOC for quite some time, but I'm stumped on how to control the length of the generated HTML filenames. I'm using nested packages and the generated filenames are so long that some filenames get truncated when written to a CD-ROM. This results in broken links when the documentation tree is copied from the CD-ROM.

I've tried using the -maxpathlen option during the (-htm) output generation phase, but this doesn't shorten the filename length.

I would like to report a minor issue with ccdoc, described below.

The documents created by ccdoc indicate that a constructor will be generated automatically by the compiler even if one is specified. This seems to occur when the constructor for class X is specified as X(X const &), but does not occur when the constructor is specifed as X(const X &), although these are equivalent.

I was going through the ccdoc for [one of my classes] this morning when I had a couple of feature ideas for ccdoc. I was thinking that it would be nice if overloaded methods in a class could be collapsed and expanded so that you only saw one line with the function name. If all of the short descriptions matched for the method, you could see the short description - if the short descriptions didn't match you would see something like "6 overloads". E.g. you might see something like this:

 +   GetClient                       Xdm_ObjectDerived       method protected   16 overloaded methods (click '+' to expand)

When you click the + to expand you would see the display much like it is today with each overload displayed on its line with its short description. At this point the '+' would turn into a '-' and clicking the '-' would collapse it back down.

Extending that idea, I thought it would be nice if we had an extra tag that we could tag methods with to categorize them - E.g. "@category Debug Helper". All methods with matching categories would go into an expandable / collapsable grouping like the overloaded methods. (If there's just one or two methods in a category maybe it defaults to expanded but more than two and the category defaults to collapsed.) Methods with no category would be displayed as they are today without the expand/collapse capability. Methods within a category are alphabetized within the category. We would also probably want links at the top and bottom to 'expand all' and 'collapse all' - maybe throw in some cookies to store the user's preferences (overall and for each class) - hah.

Then I also thought that it was somewhat annoying with the ccdoc for some classes - Xdm_Model is one example - where there is a lot of good documentation for the class but it's a pain to have to scroll through all of that to try and find the method index so I can see if it supports the method I'm looking for. Having all of the class documentation and examples are great for the first time you're using a class but for quick reference which is most of the time after the first time you've used a class, all of that stuff gets in the way. If classes could have extra tags to separate things out like @Examples, @Extending, @UserGuide or something like that then in the ccdoc, you could either have expand / collapse things like above to expand out the examples text - or you could have links that take you to the examples for a specific class etc. I like the expand/collapse symbols just to keep everything on one page but it would take some javascript or something I'm sure and may be more pain than it's worth.

Anyway, these were just some pie in the sky ideas I had this morning. I didn't think them through a whole lot - just wanted to send them off to you to see if you liked them.

---

These are very interesting ideas. I will definitely look into them for future releases.