ccmode: Doc Comments
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.
The above is by no means complete. If you’d like to see support for
other doc comment styles, please let us know (
Mailing Lists and
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’.
If you add support for another doc comment style, please consider
contributing it: send a note to <bug-cc-mode@gnu.org>.
Info Catalog
ccmode: Faces
ccmode: Font Locking
ccmode: AWK Mode Font Locking