Variable: c-doc-comment-style

c-doc-comment-style is a customizable and buffer-local variable defined in cc-vars.el.gz.

Documentation

Specifies documentation comment style(s) to recognize.

This is primarily used to fontify doc comments and the markup within them, e.g. Javadoc comments.

The value can be any of the following symbols for various known doc comment styles:

 javadoc -- Javadoc style for "/** ... */" comments (default in Java mode).
 autodoc -- Pike autodoc style for "//! ..." comments (default in Pike mode).
 gtkdoc -- GtkDoc style for "/** ... **/" comments
(default in C and C++ modes).
 doxygen -- Doxygen style.

The value may also be a list of doc comment 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 doc 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.

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 (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 have to call c-setup-doc-comment-style afterwards to redo that work.

This is a style variable. Apart from the valid values described above, it can be set to the symbol set-from-style. In that case, it takes its value from the style system (see c-default-style and c-style-alist) when a CC Mode buffer is initialized. Otherwise, the value set here overrides the style system (there is a variable c-old-style-variable-behavior that changes this, though).

Probably introduced at or before Emacs version 28.1.

Source Code

;; Defined in /usr/src/emacs/lisp/progmodes/cc-vars.el.gz
(defcustom-c-stylevar c-doc-comment-style
  '((java-mode . javadoc)
    (pike-mode . autodoc)
    (c-mode    . gtkdoc)
    (c++-mode  . gtkdoc))
  "Specifies documentation comment style(s) to recognize.
This is primarily used to fontify doc comments and the markup within
them, e.g. Javadoc comments.

The value can be any of the following symbols for various known doc
comment styles:

 javadoc -- Javadoc style for \"/** ... */\" comments (default in Java mode).
 autodoc -- Pike autodoc style for \"//! ...\" comments (default in Pike mode).
 gtkdoc  -- GtkDoc style for \"/** ... **/\" comments
						   (default in C and C++ modes).
 doxygen -- Doxygen style.

The value may also be a list of doc comment 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 doc
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.

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 \\[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 have to call `c-setup-doc-comment-style'
afterwards to redo that work."
  ;; Symbols other than those documented above may be used on this
  ;; variable.  If a variable exists that has that name with
  ;; "-font-lock-keywords" appended, its value is prepended to the
  ;; font lock keywords list.  If it's a function then it's called and
  ;; the result is prepended.
  :type '(radio
	  (c-symbol-list :tag "Doc style(s) in all modes")
	  (list
	   :tag "Mode-specific doc styles"
	   (set
	    :inline t :format "%v"
	    (cons :format "%v"
		  (const :format "C     " c-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "C++   " c++-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "ObjC  " objc-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "Java  " java-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "IDL   " idl-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "Pike  " pike-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "AWK   " awk-mode)
		  (c-symbol-list :format "%v"))
	    (cons :format "%v"
		  (const :format "Other " other)
		  (c-symbol-list :format "%v")))))
  :group 'c)