5.3 Documentation Comments

There are various tools to supply documentation in the source as specially structured comments, e.g., the standard Javadoc tool in Java. CC Mode provides an extensible mechanism to fontify such comments and the special markup inside them.

User Option: c-doc-comment-style ¶

This is a style variable that specifies which documentation comment style to recognize, e.g., javadoc for Javadoc comments.

The value may also be a list of styles, in which case all of them are recognized simultaneously (presumably with markup cues that don’t conflict).

The value may also be an association list to specify different comment styles for different languages. The symbol for the major mode is then looked up in the alist, and the value of that element is interpreted as above if found. If it isn’t found then the symbol other is looked up and its value is used instead.

The default value for c-doc-comment-style is ((java-mode . javadoc) (pike-mode . autodoc) (c-mode . gtkdoc)).

Note that CC Mode uses this variable to set other variables that handle fontification etc. That’s done at mode initialization or when you switch to a style which sets this variable. Thus, if you change it in some other way, e.g., interactively in a CC Mode buffer, you will need to do M-x java-mode (or whatever mode you’re currently using) to reinitialize.

Note also that when CC Mode starts up, the other variables are modified before the mode hooks are run. If you change this variable in a mode hook, you’ll have to call c-setup-doc-comment-style afterwards to redo that work.

CC Mode currently provides handing of the following doc comment styles:

javadoc ¶

Javadoc comments, the standard tool in Java.

autodoc ¶

For Pike autodoc markup, the standard in Pike.

gtkdoc ¶

For GtkDoc markup, widely used in the Gnome community.

doxygen ¶

For Doxygen markup, which can be used with C, C++, Java and variety of other languages.

The above is by no means complete. If you’d like to see support for other doc comment styles, please let us know (see Mailing Lists and Submitting Bug Reports).

You can also write your own doc comment fontification support to use with c-doc-comment-style: Supply a variable or function *-font-lock-keywords where ‘*’ is the name you want to use in c-doc-comment-style. If it’s a variable, it’s prepended to font-lock-keywords. If it’s a function, it’s called at mode initialization and the result is prepended. For an example, see javadoc-font-lock-keywords in cc-fonts.el. It is even possible, to a limited extent, to fontify constructs inside a doc comment with other faces. For an example, see pike autodoc comment style towards the end of cc-fonts-el.

If you add support for another doc comment style, please consider contributing it: send a note to [email protected].