[%s]\n",node->GetLongScopeName());
#endif
Thanks for taking the time to track down the code change.
ID0085:
Reported By: Scott W. Sadler
Reported On: 1999/05/25
Found In: v0.7
Status: FIXED v0.7a 1999/05/25
Brief: Ignore blank lines before the brief description.
Description:
Comment style change.
Perhaps you can incorporate this change into v0.7a. Some of our developers
insist on putting a blank-line before the brief description. I guess they
think this makes it easier to read the comment. For example:
/**
*
* this is my brief description
*
* this is my verbose & windy description...
*/
This confuses ccdoc into thinking that there is no brief description. I
modified the code so that the parsing of the brief description only stops
at the first newline *after* it actually found the brief description. In
this way the developer can have any number of blank lines before the brief
description.
In ccdocparser.cpp, line #1188
if('\n' == *p) {
// This is a blank line, we are done
// with the brief description.
#ifndef ORIG_CODE
if (p1 == briefDescription)
{
p--;
continue;
}
#endif
break;
}
On the encountering a newline, check if the briefDescription is empty. If
so, keep looking. I guess this would change the behavior if the developer
did not want a brief description, but that would seem strange. You'll have
to weigh the pros/cons of making this change.
Good suggestion. Although it changes the behavior from
previous releases, I think that it is more consistent.
ID0084:
Reported By: Joe Linoff
Reported On: 1999/05/25
Found In: v0.7
Status: FIXED v0.7a 1999/05/25
Brief: Missing '*' on comment lines confuses parser.
Description:
The following comment is not parsed correctly:
/**
brief description
full description 1
full description 2
@null
*/
void test2();
The full descriptions are merged in with the brief description.
Tested in test005.
ID0083:
Reported By: Joe Linoff
Reported On: 1999/05/24
Found In: v0.7
Status: FIXED v0.7a 1999/05/24
Brief: Incorrect name generated for "throw" methods.
Description:
Exception "throw" clauses caused the incorrect name
to be generated for methods. The following operator would
be generated with the name "throw" rather than the correct
operator name.
Foo& operator[](int) throw (ArrayBoundsException);
ID0082:
Reported By: Joe Linoff
Reported On: 1999/05/23
Found In: v0.7
Status: FIXED v0.7a 1999/05/23
Brief: Incorrect processing of enumerated type variables.
Description:
Enumerated types with variables are not processed properly.
The following structure should generate two entries: an
enumerated type and a variable but it does not.
It only generates an enumerated type entry.
/*
* Named enum.
*/
enum named_enum {EE1,EE2,EE3} named_enum_var;
ID0081:
Reported By: Scott W. Sadler
Reported On: 1999/05/20
Found In: v0.7
Status: FIXED v0.7a 1999/05/23
Brief: Anonymous enums don't work.
Description:
Anonymous enums don't work
I didn't see a bug report about this, so I'll report it. Anonymous
enumerations don't' work correctly:
/**
This is some enumeration.
*/
enum { VALUE1, VALUE2, VALUE3 };
According to the spec, the enumeration "name" is optional. If you leave
it off, ccdoc is showing the name as "{" (it just picks up the first token
after the "enum" keyword). I hacked in a fix in ccdocparsernode.cpp:
case STMT_ENUM:
{
// enum { .. }
if(GetNumItems()>1)
name = GetString(1);
#ifndef ORIG_CODE
if (!strcmp (name, "{"))
name = "[Anonymous]";
#endif
}
Not pretty, but it gets the job done. Hope you can fix it "correctly" for
v0.7a.
(I bet you are wishing I had never downloaded this thing by now, eh?)
Actually I am really glad that you downloaded this thing... Your
comments and insights are excellent. Thank you.
This will be fixed in v0.7a.
ID0080:
Reported By: Joe Linoff
Reported On: 1999/05/16
Found In: v0.7
Status: OPEN
Brief: Self extracting archive for windows.
Description:
Release the Windows version of CcDoc as a self-extracting
archive.
ID0079:
Reported By: Feng Zhou
Reported On: 1999/05/16
Found In: v0.7
Status: OPEN
Brief: Supply version information on the command line.
Description:
We use a software managing environment here (ClearCase), which
provides the version number of a source code automatically in a specific
view. How does CCDOCS work with such tools? Can I get the version number
in a shell script and pass it to CCDOCS command arguments? The only option
I find right now is to put version number in the source code, however that
wouldn't be neccessary for clearcase and not easy. Are there any routes
to avoid that?
CcDoc has no knowledge of CASE environments.
This idea of passing the @version information via the command
line is intriuging and should be fairly simple to implement.
I will look into it.
ID0078:
Reported By: Feng Zhou
Reported On: 1999/05/16
Found In: v0.7
Status: OPEN
Brief: Allow traversal to the next level on each HTML page.
Description:
We can get to any of the branches and leaf nodes of the tree from
the [Root] page. However if I click one of the branches, say app.crt, it
only shows app->crt, but there is nothing leading to the next level
(app.crt.app1, app.crt.app2) from this page, hence I can't get down the tree
from the route and have to return to [Root]. Is there a way that i can
tell CCDOCS to display the subtrees for each branch page? What should show
up for the branch itself (right now it is mostly empty since it has no
methods or class to display).
Right now there is no way to do this but this is a good
idea. I will look into it when I have time. Right now
I am somewhat swamped with v0.7a development.
ID0077:
Reported By: Huang-Ming Huang
Reported On: 1999/05/14
Found In: v0.7
Status: OPEN
Brief: Namespaces are not handled properly.
Description:
I found that ccdoc fails to generate documentation of the codes
after using declaration.
For example, in the following codes, ccdoc cannot gererate the
documentation for class Test.
namespace TestNamspace
{
class Tc;
}
using TestNamespace::Tc;
/**
* This is a test class.
*/
class Test
{
public:
Test();
~Test();
};
Name spaces don't work in the current version. They are scheduled
for a later release.
ID0076:
Reported By: Scott W. Sadler
Reported On: 1999/05/14
Found In: v0.7
Status: OPEN
Brief: Allow the documentation of a specific macro.
Description:
This is probably related to #4. We use macros to automatically slap out
exception code. Something like this:
DERIVE_EXCEPTION (my_exception, runtime_error);
This macros writes out the class "my_exception" automatically for you.
(This is a lot easier than manually writing the code for 100s of exception
types). Anyway, how can I document this "class". I want to be able to
write a doc-comment and then somehow explicitly tell ccdoc what it is
documenting. Perhaps something like:
/**
@class my_exception
brief description
full description
...
*/
DERIVE_EXCEPTION (my_exception, runtime_error);
Any way that I can do this? Keep in mind that I don't want to document the
macro or the use of the macro. I want to document the class that is
generated as a result of the macro. I guess one solution is to write a
"real" C++ preprocessor that expands out macros before actually parsing the
file. This sounds like a bit of work though...
This is very interesting.
It sounds like we could fix the problems you described in both
ID0076 and ID0075 by providing a pragma that let you explicitly define
a CTF documentation record in the absence of an associated C++
declaration. That way you could control the generated documentation
in much more detail
I really like this idea and will add as a high priority enhancement.
ID0075:
Reported By: Scott W. Sadler
Reported On: 1999/05/14
Found In: v0.7
Status: OPEN
Brief: Allow the documentation of a specific macro.
Description:
I tried using the -macro option. It ended up spitting out a ton of
useless information like you said it would. I would really rather not use
the /**@#x/ tags because I know the developers are just going to forget
them thereby causing problems. Besides, they are ugly :)
Is there any way that I can "manually" document macros. That is, is there
some tag or something that I can use that says to ccdoc, "this is a macro,
document it as such.". Therefore I can do something like this in my
headers:
/**
This macro returns the minimum of the two values.
@param p1 First value
@param p2 Second value
@macro // ???
*/
#define MAX(a,b) (((a) > (b)) ? (a) : (b))
The @macro tags allows me to explicitly specify the following construct is
a macro. ccdoc should then process it as if I had specified the -macro
switch on the command-line. However, it would ignore all other #defines
and such.
This is a good idea and I have been struggling with a generic
way of doing this. The problem is that CcDoc expects the
documentation information to be associated with a declaration
and it completely ignores macro declarations so that comment
that you suggested would be hanging in mid-air where CcDoc
would ignore it.
As a workaround, you can create pkg documentation that describes
the available macros.
ID0074:
Reported By: Scott W. Sadler
Reported On: 1999/05/14
Found In: v0.7
Status: OPEN
Brief: Ignore private classes.
Description:
Our application uses the concept of "private" or "implementation"
classes. In Java you can declare a class as "private", but there is no
equivalent way to do this in C++. As such we use a naming convention to
indicate a private class. In our environment, any class that ends with an
underscore character is part of the implementation details of a package and
should not be used by client developers.
What I want is for ccdoc to "ignore" private classes. I tried simply not
documenting the class, but ccdoc still created an HTML page for the class
including all of its member functions. What would be cool if there was a
way to specify, via some sort of regular expression, which identifiers
(class names, function names, typedefs, etc.) ccdoc should ignore. I could
then set something like:
CCDOC_IGNORE *_
to tell it to ignore all (file-scoped) identifiers that end with an
underscore. Perhaps you could have separate IGNORE clauses for each
identifier type.
That is a good idea but there is a workaroud, you can put the
following pragmas around private classes:
#ifndef __ccdoc
class CPrivate_ {
};
#endif
Meanwhile I will see if we can't add this to v0.7b or so
because this capability would be nice for systems where
the person running the documentation can't modify the source.
ID0073:
Reported By: Scott W. Sadler
Reported On: 1999/05/14
Found In: v0.7
Status: OPEN
Brief: Brief description should terminate at the first period.
Description:
Your comment blocks follow the format:
/**
Brief Description
Long Description
...
*/
What I was looking for was more of a format like Javadoc. Javadoc uses the
first sentence (everything up to the first period) as the brief
description. In this way you can just blast out your comments all in one
paragraph; javadoc will figure automatically figure out what is the brief
description. Is there any way to do this?
No, but this is an excellent idea.
The reason that CcDoc works the way it does is because
I wanted to have more than one sentence as the brief
description in some cases.
I could easily add a switch that had it work the way
that you suggested for greater javadoc compatibility.
ID0072:
Reported By: Roger Searjeant
Reported On: 1999/04/28
Found In: v0.7
Status: OPEN
Brief: Provide a class hierarchy diagram.
Description:
For deep inheritance it would be convenient to have the list of parent
classes at the top somewhere: e.g.
Object
FirstDerivedClass
SecondDerivedClass
MyClass
or something like this.
This is a good idea. It sounds like the class hierarchy
diagram requested in ID0070.
ID0071:
Reported By: Roger Searjeant
Reported On: 1999/04/28
Found In: v0.7
Status: FIXED v0.7a 1999/05/27
Brief: Nameless unions are not handled properly.
Description:
Nameless unions are not handled properly - the 'name' is taken to be the
opening brace. Not a serious problem.
I will check into this.
ID0070:
Reported By: V. Lakshman
Reported On: 1999/04/08
Found In: v0.7
Status: OPEN
Brief: Provide a class hierarchy diagram and index page.
Description:
A couple of improvements (things that are there in Javadoc) would help:
1) A class heirarchy diagram so that you can tell by looking at a class'
documentation all the parents and children of the class ( more than one
parent because of multiple inheritance).
2) An index page listing all the classes in all the packages.
These are good ideas. I definitely don't have time to get them into
v.07a but maybe v.07b will the right time.
ID0069:
Reported By: Bob Curtis
Reported On: 1999/04/06
Found In: v0.7
Status: FIXED v0.7a 1999/05/26
Brief: Header concatenation problem.
Description:
Since there is very little chance of using wild cards in the header file names,
I tried to run ccdoc in separate runs for each header but with the same package
that all the headers are part of:
ccdoc -ctf DKPServ.ctf -log run.log -pkg DKP.Service.Utility include\DKPMode.hpp
ccdoc -ctf DKPServ.ctf -log run.log -pkg DKP.Service.Utility include\DKPNameValue.hpp
ccdoc -ctf DKPServ.ctf -log run.log -pkg DKP.Service.Utility include\DKPError.hpp
Only the last header class appeared in the generated HTML.
How do you concatenate headers? I have to many to place on one command line.
I do know that placing two headers on the same (last) command line will bring
both classes in under the package name, so it is just a concatenation problem.
ccdoc -ctf DKPServ.ctf -log run.log -pkg DKP.Service.Utility include\DKPNameValue.hpp include\DKPError.hpp
I have not seen this problem and will investigate as soon as possible.
Workarounds:
1. try wildcarding, it should work.
2. another option is to put all of the files on a single line.
Wildcarding has been fixed on windows systems,
multiple headers work correctly.
ID0068:
Reported By: Witteveen, E.Y.
Reported On: 1999/04/06
Found In: v0.7
Status: FIXED v0.7a 1999/05/23
Brief: Operator parsing problem.
Description:
When I used your program, I discovered some difficulties with a operator.
template
class Array
{
/** returns the element at an certain position
* @param n The position from which the element should be taken
* @returns The elemt at the given position
* @exception IndexOutOfBoundsException
*/
ArrayType &operator[](int n) throw (IndexOutOfBoundsException);
}
Adds to methods the method throw... but there should be added an operator.
Q1. How do i work around this?
Q2. cant u atomatic add the throw-list to the documentation?
I will put together a test case for this and try to determine
what is happening in v0.7, maybe I can fix it in v0.7a.
ID0067:
Reported By: Philip Kemplin
Reported On: 1999/04/06
Found In: v0.7
Status: FIXED v0.7a 1999/09/26
Brief: Constructor arguments lists are not generated properly.
Description:
I've downloaded the V.07 release, and I've noticed something odd.
I may be doing something wrong, but one of my classes's constructor
requires three arguments. There is no default (no argument) constructor.
When I look at the html generated, there is a default constructor w/ no
arguments (which isn't in my class definition).
Can you validate this? Is this a bug? Is there a work around?
The following information is generated correctly in v0.7a:
class test027_A {
public:
test027_A(int a,int b,int c);
};
ID0066:
Reported By: Damien Quilot
Reported On: 1999/03/16
Found In: v0.7
Status: FIXED v0.7a 1999/05/23
Brief: Wildcard handling does work properly under Windows 98.
Description:
Wildcard handling does work properly under Windows 98.
You get a message something like this:
c:\perso\pfe\prog\mad\testccdoc>ccdoc -ctf test.ctf -pkg test *.x
File not found "C:\perso\pfe\prog\Mad\testccdoc\ccdoc-z-304377.txt
[further info from Damien]
okay joe,
I have fixed the problem.
Well, I have opened the source under MS visual c++ 6
And I have seen in the help an interesting note:
"Command-line arguments are handled by a routine called
_setargv (or_wsetargv in the wide-character environment),
which by default does not expand wildcards into separate
strings in the argv string array. You can replace the normal
_setargv routine with a more powerful version of _setargv
that does handle wildcards by linking with the Setargv.obj
file. If your program uses a wmain function, link with
Wsetargv.obj."
The workaround is to list each file individually until
the fix is available. I will try to get it into v0.7a.
ID0065:
Reported By: Sebastian Graca
Reported On: 1999/03/16
Found In: v0.7
Status: FIXED v0.7a 1999/05/23
Brief: @see hyperlink is not translated properly.
Description:
I have also a question concerning CcDoc. I don't know if it's a
feature or another bug, but when I used following directives:
---8<----------------------
@see aClassName
@see anotherClassName
@author me of course
---8<----------------------
the second @see directive (anotherClassName) didn't translated into a
hyperlink in generated html file (it was valid class name).
Everyhing went to normal when I removed empty line between @see and
@author.
This problem occurred because CcDoc does not trim trailing
whitespaces from @see pragmas. This will be fixed in v0.7a.
ID0064:
Reported By: Sebastian Graca
Reported On: 1999/03/16
Found In: v0.7
Status: FIXED v0.7a 1999/05/24
Brief: Polish national characters are ignored.
Description:
I've found a bug in CcDoc and... I've fixed it :)
The bug was, that when I used high ASCII characters (Polish national
characters) in CcDoc comment, ther were skipped in generated html
files (they were already skipped in ctf file).
The fix is to change all lines:
---8<----------------------
if(*p < ' ' && *p != ' ' && *p != '\t')
---8<----------------------
into
---8<----------------------
if(!(*p < 0) && *p < ' ' && *p != ' ' && *p != '\t')
---8<----------------------
in ccdocparser.cpp
This fix will be added to v0.7a.
ID0063:
Reported By: Lou Sanchez-Chopitea
Reported On: 1999/02/19
Found In: v0.7
Status: FIXED v0.7
Brief: Dummy statements to allow specific macro documentation.
Description:
Can CcDoc be modified to allow us to input dummy statements
to document functions that occur in MACROs?
// You have defined a class that is used
// in a macro that has certain methods
// that are only defined in the MACRO
// because they are type specific but
// you want to document them with the
// base class.
/** ... */
class CArray {
public:
/** ... */
CArray(long sz);
/** ... */
long GetSize() const;
/**
* This method adds a type specific element
* to the array.
*/
/**@@signature long Add(const type& elem); */
};
#define DEFINE_ARRAY(type) \
class CArray_## type : public CArray { \
public: \
CArray_##type (long sz) : CArray(sz) {}\
long Add(const type& elem); \
};
This can be done using the pre-defined __ccdoc__ macro as follows.
/** ... */
class CArray {
public:
/** ... */
CArray(long sz);
/** ... */
long GetSize() const;
#ifdef __ccdoc__
/**
* This method adds a type specific element
* to the array.
*/
long Add(const type& elem);
#endif
};
ID0062:
Reported By: Nico De Ceualer
Reported On: 1999/02/16
Found In: v0.7
Status: FIXED v0.7a 1999/06/03
Brief: Merge CTF files.
Description:
I've been implementing the ccdoc engine in our project now, and I've got a
couple of remarks about it's use:
Is it possible to generate HTML out of a list of .ctf files? Now we
rebuild one big .ctf file from scratch everytime we rebuild the
documentation, but we'd like it to only rebuild the .ctf file(s) for the
changed .h files. Is it possible to merge different .ctf files in one .ctf
file? Or do you propose to generate different html files for different
chunks in a big project? I wouldn't like to do that, because then we'd loose
the package's advantage.
CcDoc was designed to work off of a single large ctf file in
version 0.7 because it has to generate a cross reference of
the C++ entities (the phase 2 stuff).
If you generate HTML out of a list of CTF files there will
be no interfile cross references.
It is possible to merge different phase 1 ctf files but
you would still have to run the -index phase (phase 2)
to get the correct cross references which would result
in one large CTF file at the end for HTML generation
(phase 3).
I believe that it would be relatively straightforward to
enhance CcDoc to merge multiple phase 1 ctf files during
indexing. This would allow you to keep ctfs around for
code that had not changed.
We decided that this merge approach will work for Nico's
environment. This will be incorporated into v0.7a as
part of the modification for handling source files because
the run-time for generating documentation may go up
dramatically when implementation files are included in
the processing.
In version 0.7a a perl script called ctf_merge.pl will
be provided that merges CTF files. This script can
be used as follows:
% perl ctf_merge.pl -i a.ctf -i b.ctf -i c.ctf -i d.ctf -o out.ctf
% ccdoc -ctf out.ctf -index
Note that you have to regenerate the index.
ID0061:
Reported By: Lars Fastrup Nielsen
Reported On: 1999/02/03
Found In: v0.7
Status: FIXED v0.7a 1999/05/26
Brief: Add a -prolog or -header switch.
Description:
I really like your -trailer <file> option, but how about a -prolog
<file> option that would insert custom HTML code just after the
<body> clause as well?
This was added in v0.7a as the -header switch.
ID0060:
Reported By: Christophe L. Galerne
Reported On: 1999/02/01
Found In: v0.7
Status: OPEN
Brief: Replace CTF with XML.
Description:
Why not generate XML instead of a proprietary format (CTF) of your own ?
That way people could use others tools to exploit the parsing done.
The XML output format is a great idea!
I defined CTF for compactness but if XDL can provide the same
level compaction I will switch over to it. If not, I still
think that CcDoc should be able to generate it.
I consider this a medium priority enhancement.
ID0059:
Reported By: Huang Wei
Reported On: 1999/01/28
Found In: v0.7
Status: CLOSED
Brief: Add a Windows GUI.
Description:
Why not add a windows UI to CcDoc ,something like WinZip?
I like the idea but I don't think it is a high
priority in the near future because CcDoc runs
on many platforms other than Windows (Solaris,
HP UX, IBM AIX, Linux to name a few) and most
folks seem to use it in batch mode (based on
my mail messages).
For a batch oriented paradigm, a GUI is often
more of a hindrance than a help.
In addition, writing a GUI that runs equally
well on many platforms is challenging which
means that the effort would have to be
justified by user demand.
You are the first person to mention this from
over 200 users. I will log it as an enhancement
request and see what sort of demand there is.
I strongly encourage you to write the GUI for
Windows and make it available to folks who want
it.
I would be happy to incorporate it into the CcDoc
web site.
ID0058:
Reported By: Joe Linoff
Reported On: 1999/01/28
Found In: v0.7
Status: FIXED v0.7a 1999/06/10
Brief: Read comments from implementation files.
Description:
Allow CcDoc to read comments from implementation files (.cpp) as well
as from interface files (.h). This has been requested by a number of
folks over the past year and I have been struggling with an approach
that would work consistently. Recall that the class structure defines
the scope of an encapsulated entity and that this information is not
available in the implementation file.
My solution is add another processing step that occurs after the
interface files have been read and the CTF file has been created
that will read comment structures for class methods only in C++
files. The new pass would be designated by a -imp_comments switch.
If a method is found with valid CcDoc comments and the signature
matches a method in the CTF file, the comments are subsumed.
This will be one of the major changes in v0.7a.
ID0057:
Reported By: Hans Keppens, et al
Reported On: 1999/01/18
Found In: v0.7
Status: FIXED v0.7a 1999/05/27
Brief: Allow embedded hyperlinks like @see.
Description:
This was reported by a number of folks including Lars F. Nielsen.
> 2. in version 0.6, we used extra hyperlinks in the description
> of a class: for instance, listing the most important methods, with
> a small description of the protocol. The hyperlinks used the
> knowledge that the methoddefinition was preceded by a
> <A NAME="methodname"> HTML tag. This seems to have
> changed in the v0.7, into unique references, without any logical
> link to the methodname... Could you think of doing something
> to provide a way to reference a method from the comment
> section (in version v0.8)?
Yes. This is a feature that will become available
in the next version. I have included a long winded
explanation below from another person who asked
for the same thing.
Note that the other person requested the
-use_class_names switch.
Also note that this cross reference information
is available in the CTF file (but I think that
your suggestion is more convenient).
Your idea is a good one and was the motivation
for the original scheme. Unfortunately it
caused a number of problems some of which
are enumerated below:
1. information for overloaded entities
was lost
2. file names became too long on some
systems
3. operator method names created file
names with invalid characters
4. enum and macro information were lost
file1: enum FOO {BAR,SPAM};
file2: enum FOO {WOMBAT,BLAT};
when the two files were completely
unrelated [this is technically not
overloading because they are unrelated]
For these reasons it is impossible to use
the entity names as the default but since
this is such a good idea for your application
here are a couple of other solutions that
I thought of:
1. I could add a switch that told
CcDoc to use the entity name
for the file name when it
encountered a class (only).
Perhaps something like:
-use_class_names
The danger with this switch
is if you had classes with the
same name that were used in
unrelated parts of a single
system in which case you
would lose the information for
one of them.
2. I could add a pragma that allowed
you to specify the file name in
the header.
Perhaps something like:
/**
* <short>
*
* <long>
* @author ...
* @generated_name ccdoc.r.MyClass.html
*/
class MyClass { ... };
Do either of these work for you? If so,
please let me know. If not, can you think
of another approach?
Note that my current intention is too provide the
-use_class_names switch in v0.7a.
See ID0095 for details of the fix.
ID0056:
Reported By: Hans Keppens
Reported On: 1999/01/18
Found In: v0.7
Status: FIXED v0.7a 1999/05/26
Brief: Invalid parser node name.
Description:
CcDoc has problems with the following little program:
#include <vector.h>
class Test
{
public:
Test();
virtual ~Test();
private:
vector<int>::iterator start;
};
The error message is the following:
================================================
ERROR: Found invalid parser node name: '::'
at line 9 in file 'Test2.hh'
Many times this occurs because of an unterminated macro.
To fix this, insert the /**@#;*/ pragma.
================================================
We solved the problem by creating a typedef for vector<int> and
declaring the member variable with the newtype::iterator syntax:
#include <vector.h>
typedef vector<int> IntVector;
class Test
{
public:
Test();
virtual ~Test();
private:
IntVector::iterator start;
};
It looks like the vector<int> was the culprit.
Thanks for investigating this. I will look into
it further.
ID0055:
Reported By: Hans Keppens
Reported On: 1999/01/15
Found In: v0.7
Status: FIXED v0.7a 1999/05/26
Brief: IBM AIX 4.2 porting problems.
Description:
CcDoc does not compile under IBM AIX 4.2 because
that the AIX compiler wants every template type fully
specified.
For instance, the copy constructor
CJdlSorter(const CJdlSorter& x);
changes into
CJdlSorter(const CJdlSorter<List, Item>& x);
Hans has graciously agreed to send me his changes,
I will incorporate them into v0.7a.
ID0054:
Reported By: Lars F. Nielsen
Reported On: 1999/01/14
Found In: v0.7
Status: OPEN
Brief: Handle CORBA IDL.
Description:
Upgrade CcDoc to handle IDL for folks that use
CORBA and C++.
This is an excellent idea. I will look into
it as time permits.
ID0053:
Reported By: Lars F. Nielsen
Reported On: 1999/01/11
Found In: v0.7
Status: FIXED v0.7a 1999/05/26
Brief: Invalid short comment handling.
Description:
CCDoc recognises the entire comment structure below as a short
desciption only:
/**
* Short description
*
* Long description
* @author
*/
It only recognises this format correctly:
/**
* Short description
*
* Long description
* @author
*/
This is a high priority for v0.7a.
ID0052:
Reported By: Joe Linoff
Reported On: 1998/12/30
Found In: v0.7
Status: FIXED v0.7a 1999/05/23
Brief: MIME encoding does not work for chars > 127.
Description:
The MIME encoding in libjdl does
not work properly for unsigned
char values over 127.
I have already fixed this and will
bundle it in the v0.7a release.
ID0051:
Reported By: Francois Cogne
Reported On: 1998/12/17
Found In: v0.7
Status: CLOSED
Brief: Classes are not recognized.
Description:
I tried your new version of ccdoc, I generated ctf files (and it looks
fine), I then run phase 2 and phase 3, and here is my pb :
It doesn't show any class in my pck, it took the methods from a class
(last one ???) and only display a function index showing the methods
from this class though there isn't a global function in my whole
project.
The only warning I get is somehing like this during 3rd pass:
================================================
WARNING: Unsupported type 'using' encountered for node '', it will be
ignored. I
t was orignilly defined at line 14 in './PbxSync.h'. This message will
only appear once.
================================================
I have not yet looked into this but is high on the
priority list for v0.7a.
I have been unable to re-produce this problem. It might be
a problem with the way CcDoc is invoked. For now this bug
is closed until I get new information that allows me to
reproduce it.
ID0050:
Reported By: Joe Linoff
Reported On: 1998/12/07
Found In: v0.7
Status: OPEN
Brief: Handle C prototyping for ANSI and K & R.
Description:
CcDoc gets confused by C interfaces that differentiate
by between compilers that accept function prototypes
and compilers that don't. Although this is not strictly
a C++ issue it is annoying because the function names
are reported improperly. An example of the problem is
shown below:
#ifdef PROTOS
#define _P(args) args
#else
#define _P(args)
#endif
void foo _P( (int a,int b) );
void bar _P( (int a) );
CcDoc will assume that the function names are _P because
the valid C++ syntax after pre-processing would expect
the function name to precede the parentheses.
The obvious workaround is shown below but I don't believe
that this is acceptable for third party systems.
#ifdef PROTOS
#define _P(args) args
#else
#define _P(args)
#endif
void foo /**@#-*/_P(/**@#+*/ (int a,int b) /**@#-*/)/**@#+*/;
void bar /**@#-*/_P(/**@#+*/ (int a) /**@#-*/)/**@#+*/;
Another possibility is to have CcDoc apply a heuristic when
it see's syntax of the form:
<name1> <name2> '(' '(' ...
This is dangerous because it may munge valid functions
that receive function pointers as arguments as shown
below:
unsigned int foo( (*FCT)(int ));
In this case, the current behavior would be correct and
the new behavior would be incorrect.
Yet another possibility is to add a switch that tells CcDoc
that these names (_P) are special in the input files and
are to be ignored.
This is a bit of a hack but it might be the best overall
solution.
ID0049:
Reported By: Pjotr Robotnik
Reported On: 1998/11/30
Found In: v0.7
Status: FIXED v0.7a 1999/06/05
Brief: Enhance the pre-processor to handle logical operations.
Description:
I've some feature requests for the preprocessor part of ccdoc:
(1) Comparison: #if __BORLANDC__ < 0x0500
#if __BORLANDC__ >= 0x0500
(2) (In)Equality: #if WORD_SIZE == 4
#if WORD_SIZE != 4
ID0048:
Reported By: Robert Konigsberg
Reported On: 1998/11/1
Found In: v0.6a
Status: FIXED v0.7
Brief: Add a small, unobtrusive to the top.
Description:
A small, unobtrusive [top] hyperlink at various places so you can easily
move back to the top?
In v0.7, clicking on the button GIFs will take you back to the top.
ID0047:
ID0047
Reported By: Kovalan Muniandy
Reported On: 1998/10/26
Found In: v0.6a
Status: FIXED v0.7
Brief: Volunteer list.
Description:
If other folks have volunteer to help, what can they do?
This is a great idea, starting in v0.7 I will publish a TODO list
so that other folks can contribute fixes that are part of the
overall plan for the project.
I know that the first one will be to improve the pre-processor.
ID0046:
Reported By: Kovalan Muniandy
Reported On: 1998/10/26
Found In: v0.6a
Status: FIXED v0.7
Brief: Report on-line help to a file.
Description:
> I am having problem executing the program correctly and I can't see the
> error message that it is printing out since the help scrolls it out of
> the screen. I am running
> Windows 95 and the DOS prompt has only 50 lines. ;-( I couldn't pipe the
> output to "stdout" or "more" too. *strange*
>
> I tried the following and it failed and can't figure out why:
> D:\Prototype\BuildManager\BuildManager>ccdoc -pkg myprog -html
> doc\ -index doc\ *.h
>
> So, I would like to suggest the following change:
>
> In ccdocprog.cpp:
>
> else {
> ::fprintf(stderr,"\n");
> ::fprintf(stderr, "Error: unrecognized switch '%s'\n"
> "Type \"ccdoc -help\" for more information on
> how to use ccdoc.\n", sw);
> // Usage();
> }
> continue;
This is a good idea, I will incorporate it into v0.7.
ID0045:
Reported By: Pjotr Robotnik
Reported On: 1998/10/25
Found In: v0.6a
Status: FIXED v0.7
Brief: Add a simple pre-processor.
Description:
>> The most elegant solution would be to include
>> a simple preprocessor in ccdoc. But I'll guess
>> you have still other things on your todo-list :-)
>
> Your idea of a simple pre-processor is intriuging
> and it turns out to be very timely because I recently
> added #if <0> / #else / #endif support.
>
> It would be difficult to write a full blown pre-processor
> that would consistently across all platforms but something
> a bit simpler might work well enough.
>
> I am thinking of something that might support the
> following:
>
> #ifdef <name>
> #ifndef <name>
> #else
> #endif
>
> It would not support:
>
> #if defined() ...
> The ## or # operators.
>
> Would this meet your needs? If so, I can probably
> still get it into v0.7.
I have added more complete pre-processor support than
I imagined in v0.7. Although not complete it will support
the following types of stuff:
#if ( defined(FOO) || !defined(SPAM) ) && defined(BAR)
#define THIS
#else
#define THAT
#endif
ID0044:
Reported By: Pjotr Robotnik
Reported On: 1998/10/23
Found In: v0.6a
Status: FIXED v0.7
Brief: HTML files are overwritten due to overloading.
Description:
On Windows (tested on NT 4.0) generated HTML files
are overwritten in some cases due to the fact that
Windows ignores case in filenames, e.g.
ccdoc.x.foo.html is overwritten by ccdoc.x.Foo.html
in this example:
class foo
{
public:
foo(void);
~foo(void);
};
class Foo
{
public:
Foo(void);
~Foo(void);
};
I am working on fixing this on v0.7 by moving to
a different scheme that doesn't rely on entity names
to name the files.
ID0043:
Reported By: Pjotr Robotnik
Reported On: 1998/10/23
Found In: v0.6a
Status: FIXED v0.7
Brief: #ifdef inside an enum causes problems.
Description:
ccdoc doesn't like #ifdef inside enum. Example:
enum AnEnum
{
#ifdef A_DEFINE
A_VALUE
#else
B_VALUE
#endif
};
This is a known problem. It occurs because ccdoc doesn't
resolve pre-processing pragmas. There are several work
arounds in v0.6.a. You can use the off and on pragmas
to help ccdoc ignore the pre-processing pragmas as follows:
enum AnEnum
{
/**@#-*/
#ifdef A_DEFINE
A_VALUE
#else
/**@#+*/
B_VALUE
/**@#-*/
#endif
/**@#+*/
};
Another way to handle this is to run the pre-processor first
and then run ccdoc on the pre-processed output.
Please send any ideas that you might have for a more
elegant solution.
ID0042:
Reported By: Lee Willis
Reported On: 1998/10/13
Found In: v0.6
Status: FIXED v0.7
Brief: Brief description in package index and standard banners.
Description:
> A couple of suggestions/enhancement requests:
>
> SUGGESTION 1
>
> I would like to be able to have a *brief* description in the package index,
> and a longer description in the page for the class. e.g.
>
> Package Index:
>
> FooListOf<> A collection class
>
> On the FooListOf page
>
> A collection class. The FooListOf<> class provides random-access
> collections with good insertion/deletion characterstics. yadda yadda
> ....
>
> I can think of two ways to do this right of the bat:
>
> 1) Introduce a @synopsis keyword. If the class has @synopsis defined, use
> that in the package list, otherwise use the standard class description.
>
> 2) In the package list, only list the class description til the first
> paragraph break. e.g.
>
> /**
> * A collection class <-- Only this shows in package index \
> The whole thing
> *
> | shows in the
> * The FooListOf<> class provides random-access collections | class
> docs
> * with good insertion/deletion characterstics. yadda yadda .... /
> */
> template class <T> FooListOf : ....
>
> ----------------------------------------------
> SUGGESTION #2
>
> It would be nice to be able put a standard banner on all pages. i.e. you
> put a ccdoc banner at the bottom of the page, I'd like to be able to put one
> to my company in addition to the ccdoc banner. e.g.
>
> | Yada yada yada ...
> |
> | -------------------------------------------------------------------------
> | This document is copyright (c) YoYoDyne International.
> | -------------------------------------------------------------------------
> | This documentation was generated automatically by the
> | ccdoc tool (version 0.6). Click here to submit a bug report or feature
> request.
>
> This could be a command line switch: -banner <banner.html>
> The user would specify a text file to be copied to the bottom of the HTML.
>
These are excellent suggestions, I will look into
adding them in the next release.
ID0041:
Reported By: Stefan Olsson
Reported On: 1998/10/09
Found In: v0.6
Status: FIXED v0.7
Brief: Provide package level documentation.
Description:
Please a directive that allows us to document a package.
This is a very important feature and will be available
in v0.7.
Please note that Stefan went ahead and added it to v0.6.
I would be glad to send to anyone who requests it.
ID0040:
Reported By: Olivier Darge
Reported On: 1998/10/08
Found In: v0.6
Status: FIXED v0.7
Brief: Parsing problems from v0.6x.
Description:
Here is piece of code that highlights the current
problems with ccdoc.
We've made an example with all the current problems
with ccdoc rightnow.
#ifndef _Test_hh_
#define _Test_hh_
#include <map.h>
#include <bstring.h>
typedef map<int, string, less<string> > IntegerVector;
class Tracing
{
public:
Tracing();
~Tracing();
class Debug
{
public:
Debug();
~Debug();
void Output(const char* text);
};
};
class Olivier
{
public:
Olivier();
~Olivier();
};
class Hans: virtual public Olivier
{
public:
Hans();
~Hans();
};
#endif // _Test_hh_
Problems:
---------------
1. Typedefs for template types are handled
incorrectly if the template contains more
than one parameter:
Instead of generating one name
'IntegerVector' with type 'map<int,string, less<string> >',
ccdoc generates three names
'IntegerVector',
'int' and
'string') with type 'typedef map<'
2. No support for nested classes:
The generated documentation does
not mention the 'Debug' class.
3. Incorrect handling of virtual public inheritance:
The generated documentation shows
that the class 'Hans' derives privately
from virtual and publicly from 'Olivier'.
This is incorrect.
It should be:
class Hans
extends Olivier as virtual public
4. For the destructor and the constructor, the
generated detail-documentation mentions 2 times
the methodname. Is this a feature or a bug?
public Olivier Olivier ( ) ;
public ~Olivier ~Olivier ( ) ;
Great effort! Thank you. This is now one of the test cases
for v0.7.
ID0039:
Reported By: Olivier Darge
Reported On: 1998/10/08
Found In: v0.6
Status: FIXED v0.7
Brief: Add support for nested classes.
Description:
Support for nested classes.
This is being added in v0.7 along with namespace support.
It turns out that the nested classes made it into v0.7
but the namespace support did not.
ID0038:
Reported By: Christophe L. Galerne
Reported On: 1998/09/30
Found In: v0.6
Status: FIXED v0.7a 1999/06/10
Brief: FAQ.
Description:
FAQ for CcDoc.
This is a great idea. I will do it as soon as I have time.
ID0037:
Reported By: Frederik Ramm
Reported On: 1998/09/25
Found In: v0.6
Status: FIXED v0.7
Brief: Declaring exceptions.
Description:
ccdoc is a great tool for our small team, but there is one problem
with declaring exceptions in header files. We often have the following
(might remind you of java):
/**
* ccdoc comment goes here
*/
setValue(const char *value) throws SomeException;
(Yes, this is valid syntax...) - unfortunately, ccdoc screws up such
a definition; in the HTML file, you will find a member variable named
")" and other weird stuff.
I tried to fix that myself but found the ccdoc source code a bit
difficult to understand. Perhaps you can give it a try? I don't
bother what ccdoc does with the "throws" clause, perhaps it is simplest
to ignore it, but it should not deform the .html generated.
If you don't have the time to look after this problem, perhaps
you can give me a hint where I'll probably have to change the
ccdoc source, then I might fix it myself and submit a diff.
This will be fixed in v0.7.
ID0036:
Reported By: Roger van de Kimmenade
Reported On: 1998/09/25
Found In: v0.6
Status: FIXED v0.7a 1999/06/10
Brief: Recognized the // comment form.
Description:
Is it also possible that the ccdoc tool is able to recognise the
// comment? This is because the Rose Tool generates automatically
generates comment blocks with this form.
This was fixed in v0.7a. The comment form is:
///**
// *
// *
// */
ID0035:
Reported By: Herman Harjono
Reported On: 1998/09/22
Found In: v0.6
Status: FIXED v0.7
Brief: Friend functions and classes are not reported.
Description:
Friend functions and classes are not reported.
ID0034:
Reported By: Matthias Rosenthal
Reported On: 1998/09/22
Found In: v0.6
Status: FIXED v0.7
Brief: Arguments with scope are not handled properly.
Description:
Arguments with scoping are not handled properly as shown in
the example below:
void test(AnotherClass::TypeDefinition a);
This was also reported by Ken Tsui.
ID0033:
Reported By: Joe Linoff
Reported On: 1998/08/04
Found In: v0.6
Status: FIXED v0.7
Brief: Invalid inheritance from template instantiations.
Description:
Template instantiations of classes cause invalid inheritence
to be reported as shown in the sample code below:
class CXdlLangInstanceIterator : public CXdlUtilListIterator<CXdlLangInstance> { .. };
ID0032:
Reported By: Lou Sanchez-Chopitea
Reported On: 1998/08/04
Found In: v0.6
Status: FIXED v0.7
Brief: Overloaded methods are not handled properly.
Description:
Overloaded methods are not handled properly. For an example,
see the following code,
MACRO const char* getenv(const char* name);
MACRO const char* getenv(char* name);
ID0031:
Reported By: Lou Sanchez-Chopitea
Reported On: 1998/08/03
Found In: v0.6
Status: FIXED v0.7
Brief: Make the source reference a hyperlink.
Description:
Make the source reference a hyperlink.
The idea here is that the user would be able to browse the
source code by clicking on the Source hyperlink. This is a
great idea. To implement this a switch called -srcurl <url>
will be added to tell the program how to generate the href
statement. If the switch is not specified, hyperlinks will
not be generated for the source statement.
ID0030:
Reported By: Joe Linoff
Reported On: 1998/08/01
Found In: v0.6
Status: FIXED v0.7
Brief: There is no way to add package documentation.
Description:
There is no way to add package documentation. A large number
of folks have requested this.
This is a key feature of v0.7.
ID0029:
Reported By: Huang-Ming Huang
Reported On: 1998/07/31
Found In: v0.6
Status: FIXED v0.7
Brief: Template typedef is not handled correctly.
Description:
The ccdoc program cannot handle a typedef to a template class
correctly. For an example, see the following code,
typedef ArrayMap< SOCKET, ReadHandler*, MAX_NUMBER_OF_SESSIONS > ReadReactorMapImpl;
class A { ... };
ID0028:
Reported By: Jeff Mason
Reported On: 1998/07/28
Found In: v0.6
Status: FIXED v0.6a
Brief: Handle a MACRO before a class statement.
Description:
Ccdoc should be able to handle a MACRO before the class
statement to allow programmers to define an entire class
for DLL exporting under MSCV++.
The addition of the off and on pragmas allow you to work around this problem as follows:
/**@-*/ DLL_EXPORT /**@+*/
class A { ... };
ID0027:
Reported By: Todd Hoff
Reported On: 1998/07/28
Found In: v0.6
Status: FIXED v0.6a
Brief: Images are not distributed with the documentation.
Description:
It would be good to distribute the images with the tool.
ID0026:
Reported By: Lou Sanchez-Chopitea
Reported On: 1998/07/28
Found In: v0.6
Status: OPEN
Brief: Report whether a class method is const in the method index.
Description:
Report whether a class method is const in the method index.
This is a good idea because const methods have different
semantics.
Does any one have any suggestions about what this should
look like?
ID0025:
Reported By: Lou Sanchez-Chopitea
Reported On: 1998/07/28
Found In: v0.6
Status: CLOSED
Brief: Segregate public and protected methods.
Description:
Can ccdoc allow the segregation of public and protected
methods since they apply to different audiences?
I think was is meant here is that protected methods are
used by folks who want to derive from a class and
public methods are used by folks who want to use an object
of the class. There is a third audience, the programmer(s)
who support the class. Each of these folks want to see a
different view.
My suggestion is to produce documentation in different
areas for the different audiences.
ID0024:
Reported By: Lou Sanchez-Chopitea
Reported On: 1998/07/28
Found In: v0.6
Status: FIXED v0.7
Brief: Argument lists are not always wrapped neatly.
Description:
Sometimes ccdoc will wrap long argument lists neatly, breaking
at "," but at other times it just puts it all on one line,
even if on different lines in the source.
This will be fixed in v0.7.
ID0023:
Reported By: Lou Sanchez-Chopitea
Reported On: 1998/07/29
Found In: v0.6
Status: FIXED v0.6a
Brief: Allow C++ statements to be ignored.
Description:
A comment form that allowed a C++ statement to be ignored would
be useful for discarding entities that result from macros.
This was fixed in v0.6a with the addition of the /**@-*/
and /**@+*/ ccdoc pragmas.
|