Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to do "See Also" to a book using doxygen

Tags:

doxygen

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.

like image 970
Paul J. Lucas Avatar asked May 14 '10 17:05

Paul J. Lucas


2 Answers

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?

like image 68
Dmitriy Avatar answered Jan 02 '23 23:01

Dmitriy


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.

like image 33
Chris Avatar answered Jan 02 '23 23:01

Chris