In code that uses doxygen comments, we have this:
/// #see #ref Foo::Bar()
This generates a "See also" section in doxygen with an explicit link to the Foo::Bar() class/method.
But with clang-tidy, this comment generates an error:
example.h:70:12: error empty paragraph passed to '#see' command [clang-diagnostic-documentation]
(First time I've see a code comment generate a compiler error!)
Is it really invalid to have a #ref as the content of the #see? Or is the # confusing clang-tidy?
Related
Suppose you have a rather complicated README you want Doxygen to process to produce the mainpage of the documentation, something along the lines of
/*!
\mainpage Welcome to this code
\section S1 Introduction
Some stuff to explain why you coded all this
\section S2 Examples
Many examples of how the code can be used
!!! some line which you wouldn't write in a documentation
\section S3 Some other stuff
*/
AND you want doxygen to ignore the line beginning with !!! BUT you don't want to erase the line because you plan on editing it later.
Well, how can you do that?
EDIT: The following:
/*!
\mainpage Welcome to this code
\section S1 Introduction
Some stuff to explain why you coded all this
\section S2 Examples
Many examples of how the code can be used
\cond NEVER
!!! some line which you wouldn't write in a documentation
\endcond
\section S3 Some other stuff
*/
fails to put section S3 in the mainpage...
From the HTML commands section in the manual:
Finally, to put invisible comments inside comment blocks, HTML style comments can be used:
/*! <!-- This is a comment with a comment block --> Visible text */
The following:
/*!
\mainpage Welcome to this code
\section S1 Introduction
Some stuff to explain why you coded all this
\section S2 Examples
Many examples of how the code can be used
\internal
!!! some line which you wouldn't write in a documentation
\endinternal
\section S3 Some other stuff
*/
achieves the desired goal, provided your doxyfile is set correctly ( INTERNAL_DOCS tag set to NO ). I aknowledge #albert for the tip.
I'm documenting my code using long sets of slashes to make them stand out in the code.
//////////////////////////////////////////////////////////////////////
/// #brief This is a simple test struct.
//////////////////////////////////////////////////////////////////////
struct Foo
{
//////////////////////////////////////////////////////////////////////
/// #brief Function with single line brief to demonstrate issue.
//////////////////////////////////////////////////////////////////////
void a() {}
};
I've built doxygen from a fresh subversion checkout and when it's run on the code above the line of slashes at the end of each block are included in the brief description. The problem doesn't exist in doxygen 1.8.1 that's installed on my system, so this appears to be a bug in the doxygen trunk.
I've submitted bug 700345 to the doxygen project, but am interested in taking a shot at fixing this myself.
I'm having trouble finding the code doxygen uses to detect the end of comment blocks. Does anyone have experience working with this part of the code and have a moment to point me in the right direction?
FYI, a quick solution to this is to add a blank comment line after the #brief. I'm not interested in going through ~100k lines of code to identify problematic comment blocks and add a blank line (yet).
See my proposed fix attached to the bug report you submitted.
In Org-mode you can make comments and from Org-mode you can export to LaTeX but Org-mode comments are not exported to LaTeX comments. How can Org-mode be made to export Org-mode comments as LaTeX comments?
Here is an example. The following
* Test
Text before comment
# Comment
Text after comment
Text before comment
#+BEGIN_COMMENT
Comment
#+END_COMMENT
Text after comment
exports to
\section{Test}
\label{sec-1}
Text before comment
Text after comment
Text before comment
Text after comment
But I want the Org-mode comments to be exported as LaTeX comments. Thus, I want the following LaTeX output:
\section{Test}
\label{sec-1}
Text before comment
% Comment
Text after comment
Text before comment
\begin{comment}
Comment
\end{comment}
Text after comment
I am running Org-mode 7.6 in Emacs 23.3.1.
Under the current exporter the only method I can think of that would allow you to export comments would be backend-specific. You could use something along the lines of:
#+latex: comment
or
#+begin_latex
\begin{comment}
comment
\end{comment}
#+end_latex
However both are contrived and you would need to do the equivalent for HTML etc if you intend to export to more than one format.
There is a new exporter in development however where this should not be overly difficult to implement (comments are already identified as blocks in the parser so it would simply need a method to convert them on export).
I'm forwarding this request to the mailing list to see if this can be included.
Edit: Thread located here.
Edit: Response from the maintainer of Org-Mode
the current exporters don't allow this, but the new export engine by
Nicolas makes it possible.
The plan is to merge the new export engine into Org's core before
version 8.0, so please stay tuned.
In addition to Jonathan Leech-Pepin's answer, there is a hackish way of doing it for a given exporter backend. Comments are handled in the org-export-handle-comments function, which is called by org-export-preprocess-string in org-exp.el. Each exporter backend is different, but let us consider the LaTeX backend.
If you look in the org-export-as-latex function in org-latex.el, you can find calls to org-export-preprocess-string. One of the things passed to the org-export-preprocess-string function is a parameter list, in particular it contains a :comments parameter, which in the LaTeX case is set to nil. This parameter tells the org-mode exporter what to do with comments - for the details look at the call to and implementation of org-export-handle-comments in org-exp.el. Essentially, the :comments parameter can be a format string showing how to handle the comments; if it is nil, this means no format handling so nothing is printed. If, in the org-export-as-latex function, you replace :comments nil with :comments "%% %s", then this will insert a "%" in front of whatever the comment text is upon export. So in your case
this is text before a comment
# this is a comment
this is text after a comment
would be exported as
this is text before a comment
% this is a comment
this is text after a comment
This isn't the most convenient way of doing things, and I'm not sure of a way to specify the :comments parameter on a per-file basis. Maybe something in the thread Jonathan set up will shed some light on this subject.
Note that you may need to remove the byte-compiled org-latex.elc file in order to see your changes in org-latex.el propagate through to the export.
I've just installed and setup an instance of Doxygen, but out of the box it only finds TODO tags in code when marked in a block like:
/**
* #todo Foo
*/
It doesn't seem to find:
// TODO Foo
// FIXME Bar
// #todo Baz
Most IDE's and bug trackers which handle parsing are fine with them, is there an easy way to configure Doxygen to find them and list them as ToDo items?
There are a number of examples and methods we can use:
For a one line comment with valid doxygen commands (e.g. \todo) you would use
/// \todo Some (optional) text
Note the three forward slashes, not the usual two. See point three on the second list in the special documentation blocks section of the doxygen documentation. This can be used to add new todo items to your source code.
Generally one can define custom tags (like FIXME) by defining an alias in the Doxygen configuration file. For example
ALIASES += FIXME="\todo"
which will allow you to write \FIXME in your source code and the comments prefixed with \FIXME will be included in you todo list in the final documentation. The problem here is that you have to prefix your aliases with the \ (or #) symbol and begin the comment with three leading forward slashes which, if you want to leave the FIXMEs in your code as they are, is not an option.
Finally, an alternative method, and what I think you are looking for, would be to preprocess your source files using the INPUT_FILTER configuration file option. This option defines a command that is applied to each of your source files before doxygen builds the documentation, so we can define a command which replaces instances of TODO and FIXME with valid doxygen markup.
INPUT_FILTER = "sed -e 's/\/\/.*FIXME/\/\/\/ \\todo/'"
This filter replaces all instances of // FIXME (with any amount (or none) of whitespace between // and FIXME) with /// \todo. This substitution is made internally by doxygen only: your source files are not modified on disk.
Note: This last point was inspired by the accepted answer to the question Getting doxygen and MSVC TODO tags to work together. However, that answer used the FILE_VERSION_FILTER configuration option rather than INPUT_FILTER. I think that the latter (INPUT_FILTER) is actually more appropriate here. Also, the sed command used in that answer does not work for me.
The Javadoc #see allows a simple string as an argument to refer to something like a book, e.g.:
#see "The Java Programming Language."
As far as I can tell, the Doxygen \see offers no equivalent. Is there any way to have a book reference generated in the documentation, e.g.:
See Also
The C++ Programming Language, Bjarne Stroustrup, Addison-Wesley, 2000, section 19.4.1: The Standard Allocator
?
Clarification
This question is about how to do a "See Also" as part of a comment, e.g.:
/**
* Allocates memory in an amazing way.
* \param size The number of bytes to allocate.
* \return Returns a pointer to the start of the allocated memory.
* \see MyOtherClass::alloc()
* \see "The C++ Programming Language," Bjarne Stroustrup, Addison-Wesley, 2000,
* section 19.4.1: The Standard Allocator.
*/
void* my_alloc( size_t size );
Of course the above does not work in Doxygen. Note that if there are multiple \see tags, they should be merged into a single "See Also" section (like the way \see normally works.
I tried multiple \see in my project and doxygen merges it into single "See also" section:
/// \see MyOtherClass::alloc()
/// \see "The C++ Programming Language," Bjarne Stroustrup, Addison-Wesley, 2000,
/// \see 3
/// \see 4
Output is:
See also:
MyOtherClass::alloc()
"The C++ Programming Language," Bjarne Stroustrup, Addison-Wesley, 2000,
3
4
Are you using latest version of doxygen?
Whilst, I am a bit late to this, hopefully the following is helpful.
You can in fact use a string with the \see command (which is included for compatibility with Javadoc and is simply an aliases to \sa), as Dmitriy has shown, even if this is undocumented.
Alternatively, and perhaps more properly, you could try using the \cite command to add a bibliographic reference .
Finally, you state that
Note that if there are multiple \see tags, they should be merged into a single "See Also" section (like the way \see normally works[)].
Doxygen does merge multiple \see's and \sa's together as Dmitriy demonstrates. However, in the comments to Dmitriy's answer, you state that
I never claimed that Doxygen doesn't merges multiple \see together: I said that if I were to define my own tag, it wouldn't merge that together with \see since it would be my own tag and not a \see.
It is possible to define your own tag and have it merged into the "See also" section if your tag is an aliases to \sa.
If your question is about styling, you can define your own tag with ALIASES configuration option.
If your question is about creating a bibliography page, you can define a specific cross reference tag, using \xrefitem tag.
Of course, you can combine both.
If your question is about handling a bibliography database, ala EndNote or BibTeX, I'm afraid Doxygen is not the best tool.