How to do "See Also" to a book using doxygen - 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.

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.

Related

How to write diff code with syntax highlight in Github

Github supports syntax highlight as follows:
```javascript
let message = 'hello world!'
```
And it supports diff as follows: (but WITHOUT syntax highlight)
```diff
-let message = 'hello world!'
+let message = 'hello stackoverflow!'
```
How can I get both 'syntax hightlight' AND 'diff' ?
No, this is not a supported feature at this time.
GitHub documents their processing of lightweight markup languages (including Markdown, among others) in github/markup. Note step 3:
Syntax highlighting is performed on code blocks. See github/linguist for more information about syntax highlighting.
If we follow that link, we find a list of grammars that Linguist uses to provide syntax highlighting on GitHub. Linguist can only apply one of the grammars in that list to a block of code at a time. Of course, one of the grammars is Diff. However, that grammar knows nothing about the language of code being diffed, so you don't get syntax highlighting of that.
Of course, there are other languages which are often combined. For example, HTML is often included in a templating language. Therefore, in addition to the HTML grammar, we also find grammars for HTML+Django, HTML+ECR HTML+EEX, HTML+ERB, and HTML+PHP. In each case, the single grammar is aware of two languages. Both the specific templating language and the HTML which is interspersed within the template.
To accomplish the same thing with a diff, you would need a separate "diff" grammar for every single language listed. In other words, the number of grammars would double. Of course, a way to avoid this might be to treat diff differently. When diff is specified, they could run the block through the syntax highlighter twice, once for diff and once for the source language. However, at least when processing code blocks in lightweight markup languages, they have not implemented such a feature.
And if they ever were to implement such a feature in the future, it would likely be more complicated that simply running the code block through twice. After all, every line of the diff has diff specific content which would confuse the other language grammar. Therefore, every grammar would need to be diff aware, or each line would need to be fed to the grammar separately with the diff parts removed. The problem with the later is that the grammar would not have the context of each line and is more likely to get things wrong. Whether such a solution is possible is outside this cope of this answer, but the point is that it is reasonable to expect that such a feature would be much lower priority to support due to the complexity involved.
So why does GitHub do syntax highlighting in other places on its website? Because, in those cases, it has access to the two source files being diffed and it generates the diff itself. Each source is first highlighted (avoiding the complexity mentioned above), then the diff is created from the two highlighted source files. However, a diff included in a Markdown code block is already a diff when GitHub first sees it. There is no way for them to highlight the pre-diff code first. In other words, the process they currently use would not be transferable to supporting the requested feature.
You would need to post-process the output of the git diff in order to add syntax highlighting for the right language of the file being diff'ed.
But since you are asking for GitHub, that post-processing is not in your control, and is not provided by GitHub at the moment in its GFM (GitHub Flavored Markdown Spec).
It is supported for source files, in a regular diff like this one or in a PR: GitHub does the syntax highlighting of the two versions of the file, and then computes the diff.
It is not supported in a regular markdown fenced code block, where the +/- of a diff would throw off the syntax highlighting engine, considering there is no "diff" operation done here (just the writer trying to add diff +/- symbols)

Can environment variables in Doxygen be expanded when they are arguments to commands?

I am using Doxygen (version 1.8.8) and am having a problem expanding an environment variable within a section command.
The syntax for the section command in Doxygen is given as:
\section <section-name> (section title)
I would like to expand an environment variable as part of the section title. That is:
\section MY_SECTION $(MY_ENV_VARIABLE)
However, in the generated HTML documentation, $(MY_ENV_VARIABLE) has not be expanded. If I put $(MY_ENV_VARIABLE) in a paragraph, it does expand correctly.
\section commands are limited in what commands are supported as part of their argument.
It makes sense to support environment variable expansion though, so feel free to file an enhancement request for this here: https://bugzilla.gnome.org/enter_bug.cgi?product=doxygen

What does it mean "See something(3) or see something-else(5), etc..." in the man of a command in terminal? [duplicate]

This question already has answers here:
What does the number in parentheses shown after Unix command names in manpages mean?
(7 answers)
Closed 4 years ago.
I have a simple question I made my self but didn't find any answer and hints.
When I type for the man entries of a command, e.g. "man git", I get the following:
...
DESCRIPTION
...
See gittutorial(7) to get started, then see Everyday Git[1] ...
The Git User's Manual[2] has a more in-depth
introduction.
After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git
commands with "git help command". gitcli(7) manual page gives you an overview of the command line command syntax.
Formatted and hyperlinked version of the latest Git documentation can be viewed at http://git-htmldocs.googlecode.com/git/git.html.
Could someone explain what are those "See gittutorial(7)...Everyday Git[1]...gitcli(7)" etc.? I mean, I know that they are telling "look at this resource if you want to know the basic concepts, for more info, etc.", but actually how should one interpret it?
What is the meaning of the numbers (like 7, 1, 2, etc..) inside the parenthesis or brackets? And where I can find the resources the manual is telling me to see, do I have to type something in the man prompt, or search on the Internet?
I just would like to ask for an elucidation.
Thank you for your attention!
Man pages are splitted into sections
to access a manual page inside a specific section you prepend the section number before the manpage name, for example try:
man 3 fork
or
man 2 fork
Usually the square braketed numbers are links to additional material in the NOTES section of the manpage (scroll to the bottom)
The parenthesized numbers indicate in which section of the manual the referenced entry appears. Section (1) is commands (programs), section (2) is system call functions, section (3) is general library functions, etc. Some terms have distinct entries in multiple sections. For example, this ...
man 1 printf
... gives a different manual page (from section 1, describing the printf program) than does this ...
man 3 printf
... which gives a page from section 3, describing the printf() function from the C standard library.
It means type man 7 gittutorial for more info. Man page are divided in numbered categories, sometimes overlapping. Use apropos git for instance to see the various possibilities.
The numbers in parentheses, manpage(N), are the manual section, each of the 8 sections covers a different topic.
See man-mages(7) ;) for a list of sections:
man man-pages
And you can open a manpage from a given section by including the number in the command:
man 7 man-pages
The numbers give you a hint of what the manpage will cover, e.g. time(1) is about a command, whereas time(2) is about a system call, and let you specify which section of the manual you're interested in when there's an entry with the same name on different sections.
The numbers between brackets, something[N] are footnotes, usually pointing to places where you can get more information.

What is the documentation created by doxygen called

As I understood it "javadoc" is the name of the tool that generates html-documentation which also goes by the name javadoc. Atleast that is how I've been using the words..
But what is the generated output of the tool doxygen called? Doxygen-doc? doxy-doc? or maybe something else?
(Question in c++ context, if it matters)
Separate the tools from the output format.
Javadoc is a markup system. I think it is incorrect to call its html output (or any other output) "javadoc". The same way as you would not call a web page styled in Word "Word".
Similarly, Doxygen is also a markup system. It does not have its own documentation output type. Its 'types' are the output types it supports, that is: HTML, Latex, Man pages, RTF and more. See the full list.
You mention C++. Doxygen supports "C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.
See Overview.
Short answer: "Design Documentation"
It's not a file format, it's a type of document that can be in any format. Usually html if you used Doxygen to create it.

Can Doxygen easily be configured to recognise TODO and FIXME lines?

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.