This document describes the major changes and features that you need to be aware of when moving from v0.7a to v0.8. For more information about any of these changes, see the users guide.
Change 1: No ccdoc.index.html file. |
In previous versions of ccdoc, the root package was always named ccdoc.index.html. In this version this convention was changed because the root package was the same as any other package and I wanted the output to be consistent. Unfortunately, this means that many users might be stranded because they have already built systems that expect to find ccdoc.index.html.
This example shows how to create a root package file with the name ccdoc.index.html.
% ccdoc -db simple.db simple.h -html webdocs/ \ -rootfile ccdoc.index.html
Change 2: Unique HTML file names. |
In previous versions of ccdoc, the output HTML file names were semi-random. In this version they are consistent and do not change between runs. This means that you can safely link to them from other documents.
Change 3: Namespace support. |
Namespaces are supported.
Change 4: //@{ .. //@} |
This version of ccdoc supports the C++ end of line comment form. This provides a way of guaranteeing that you don't have run-away comments in your code. An example is shown below:
// ================================================================
//@{
// This is a standard ccdoc style comment using the '//' comment
// form. It is exactly the same as the previous form.
// @author Foo Bar
// @version v1.0
// @see Stuff
// @see <a href=../webdocs/foo.htm>Foo Package</a>s
//@}
// ================================================================
Change 5: @deprecated |
Specifies that this interface has been deprecated. You should specify what to use as an alternative. Here is an example of its use:
/** * Get something. * @deprecated Use this * @link Better::Function new function * to get better results. */ Something at_deprecated();
Change 6: @link |
Generate a hyperlink to a ccdoc entity anywhere in the the code without generating an entry in the See section.
The <entity> is the ccdoc entity to link to. The <name> is the user name of the link. It can consist of one or more tokens. Leading white space is ignored.
If the name is not specified, the <entity> name is used.
Here is an example of how it is used:
/** * This function is closely associated with * @link at_link2 the at_link1 function. */ void at_link1(); /** * This example shows how the @link uses the * default name. * This function is closely associated with * @link at_link2 * . */ void at_link2();
Change 7: @pkgdoctid |
This directive must be specified after @pkgdoc. If it isn't a warning will be generated and the directive will be ignored.
It allows you to redefine the pkgdoc title id. Normally when a package name is specified the title on the page is "package <name>". With this directive you can change the "package" string to anything you like.
It was added because some users would like to define different semantics for different packages, for example: some package might be subsystems, others might be modules and still others might really be packages. With this directive you can change the name in the generated HTML file to better reflect package semantics in your environment.
The example below shows how to define three packages: A, B and C. A is the top level, B and C are children. A will be reported as a "system", B will be reported as a "module" and C will be reported as a "subsystem".
/**
* @pkgdoc A ../doc/A.html
* @pkgdoctid system
*/
/**
* @pkgdoc A::B ../doc/A.B.html
* @pkgdoctid module
*/
/**
* @pkgdoc A::C ../doc/A.C.html
* @pkgdoctid subsystem
*/
Change 8: @suffix |
This is a suffix style comment, that is, it is attached to the preceding statement rather than the following statement as shown in the example below:
void at_suffix();
//@{
// This is the C++ style suffix comment
// form that some folks have requested.
// @suffix
//@}
Change 9: -db <file> |
The name of the ccdoc database. The -ctf switch has been deprecated and may go away in future versions.
Change 10: -version |
Report the program version. The version contains the program name, the version, the revision, the release date and the compilation id. Here is an example of what the -version reports:
% ccdoc -version
ccdoc v0.8 r11 2001/09/02 bin_opt_msvc_MSWin32-4.0
Change 11: -[no]cdsms |
These are phase 1 switches.
Turn on or off the creation of default special members for classes. Specifically this tells ccdoc to create (or not create) entries for default constructors, copy constructors, destructors and copy operators if they were not explicitly defined in the class. The default is -cdsm.
Change 12: -rpt switches |
These are phase 3 switches that give the user much more control over what is reported. Here is a summary of the switches. For additional details see the users guide.
| Switch | Description |
| -[no]rptcsd | New. Report class summary details. When -rptcsd is specified, the class summary page reports type, access and short description information. When -norptcsd is specified the class summary page only reports the names. The default is -rptcsd. |
| -[no]rptdpa | New. If the package author is not specified, report the author as unascribed. The default is -norptdpa which tells ccdoc to ignore authors on packages unless they are explicitly specified. |
| -[no]rptdpd | New. If the package description is not specified, report the description as unknown. The default is -norptdpd which tells ccdoc to ignore descriptions on packages unless they are explicitly specified. |
| -[no]rptdpv | New. If the package version is not specified, report the version as unknown. The default is -norptdpv which tells ccdoc to ignore version on packages unless they are explicitly specified. |
| -[no]rpthpc | New. Report package contents hierarchically like the the class summary page. The default is -rpthpc. |
| -[no]rptim | New. Report all inherited methods as though they were defined locally. This allows you to read all of the methods that are available on a given class. The default is -rptim. |
| -[no]rptmac | New. Report macros. Default is -notprmac because there can be large numbers of guards in header files. If a system is designed with ccdoc in mind, the header guards can be surrounded by ccdoc guards (#ifndef __ccdoc__) which would make this data more useful. |
| -[no]rptpri | New. Report private items. The default is -norptpri. |
| -[no]rptpro | New. Report protected items. The default is -norptpro. |
| -[no]rptpub | New. Report public items. The default is -rptpub. |
| -[no]rpttyp | New. Report typedefs. Default is -rpttyp. |
| -[no]rptun | New. Report unions. Default is -rptun. |
Change 13: -ctf is deprecated |
The -ctf switch has been deprecated to inform the user that the database format has changed. The preferred switch -db. For additional details see the users guide.
Change 14: -imgurl is no longer needed |
The new version of ccdoc does not use images so this switch is not used. For additional details see the users guide.
Change 15: -fgtext, -fglink, -fgvlink for better color control |
These are phase 3 switches that give the user much more control over colors. For addition details see the users guide.
| Switch | Description |
| -bg <color> | The background color. The default is the default for the browser. |
| -fgtext <color> | The foreground text color. The default is the default for the browser. |
| -fglink <color> | The foreground link color. The default is the default for the browser. |
| -fgvlink <color> | The foreground vlink color. The default is the default for the browser. These are used links. |
Change 16: package tree view has changed |
The package view was previously organized as a tree with a large amount of horizontal white space. This has been changed in the new version to allow the package description to be incorporated. I also think that it is more readable.
Change 17: template class method implementations |
Template class method implementations do not work correctly in either version. Always document the template class method definition and tell ccdoc to ignore the implementation as shown in the example below:
#if !defined(header_guard)
// Tell ccdoc to ignore the header_guard macro.
#if !defined(__ccdoc__)
#define header_guard
#endif
/**
* This is a template class.
*/
template <class T>
class A {
public:
/**
* Constructor.
*/
A();
/**
* Destructor.
*/
A();
};
// ================================================
// Tell ccdoc to ignore the template class
// implementations.
// ================================================
#if !defined(__ccdoc__)
template <class T> A<T>::A()
{
}
template <class T> A<T>::~A()
{
}
#endif
#endif // header guard
Although this is not strictly a difference between the versions it is important to remember the workaround.
Change 18: -D option works in v0.8 but does not work in v0.7a |
The -D option works in v0.8, but does not work in v0.7a, even though it is said to work in the v0.7a Users Guide. This can be confusing for users that have experience with v0.7a.
Change 19: Issue 0082: Short description syntax is different (in r24 or later). |
The short description syntax in older versions of ccdoc was not compliant with the javadoc standard. The newer versions of ccdoc have been upgraded to conform to the standard and a new switch -nojdsds was added to allow backward compatibility.
Change 20: @since |
This directive is supported in r24 or later.
This is entity has only been available since the specified version. Ccdoc does not impose any syntax requirements on the version string so you can use anything you want.
The example below shows how to use this directive.
class A {
public:
/**
* Get the name of the object.
* @returns The name of the object as a "C" string.
* @deprecated This function will go away in build 12.
*/
const char* get_name() const;
/**
* Get the name of the object.
* @param name The string to return the name to.s
* @since v1.2 Built 2001/10/10.
*/
void get_name(string& name) const;
};
For more information see the users guide.
Change 21: @throws |
This directive is supported in r23 or later.
It is synonymous with @exception.
Change 22: {@link...} |
This directive is supported in r24 or later.
It is very similar to the @link directive except that it can be embedded inside comment lines. Like @link, it tells ccdoc to generate a hyperlink to a ccdoc entity. Unlike @link the arguments are not optional.
You must specify both the entity and the link name.
You must not embed white space in the '{@link' specification. For example, '{ @ link' is not valid.
Any number of link specifications are allowed on a single line.
Invalid {@link...} specifications are output as simple text.
The example below shows how it is used:
class A {
public:
void fct1();
void fct2();
void fct3();
/**
* See {@link #fct1 x}, {@link #fct2 y} or {@link #fct3 x} to
* figure out how this stuff works.
*/
void fct4();
};
The <entity> is the ccdoc entity to link to. The <name> is the user name of the link. It can consist of one or more tokens. Leading white space is ignored.
For more information see the users guide.