Doxygen @code line numbers

10
votes

Is there a way to display code line numbers inside a @code ... @endcode block? From the screenshots in the doxygen manual it would seem that there is, but I was unable to find an option for doxygen itself, or a tag syntax to accomplish this.

I need this to be able to write something like "In the above code, line 3" after a code block.

Tested also for fenced code blocks, still getting no numbers.

1
doxygen
Two questions come to mind. 1. Which 'line numbers' do you want- the line numbers of the doxygen comment within the file, or relative line numbers of the source quoted in the comment? 2. Where in the doxygen manual do you see these screen shots? I'm looking at the \code section of the online manual and not seeing anything. - Cheeseminer
@Cheeseminer: I am interested in the latter line numbers (the relative ones). As for an example of what I mean, check out this section of the manual: stack.nl/~dimitri/doxygen/manual/markdown.html#md_fenced - neuviemeporte
Hmm. Out of interest what code language are you documenting? That example is notably within the Markdown section and commenting python code; whereas the equivalent C code example doesn't have them. I wonder if it's a consequence of whatever interpreter is used by doxygen for Markdown. It's not standard Markdown. I'm out of suggestions, sorry. +1 for the question. - Cheeseminer
I am indeed using C code. I don't suppose adding {.py} to my @code will work very well... Seems like you are right, though - apparently code lines are not supported for C, which is strangely arbitrary. - neuviemeporte

1 Answers

1
votes

Short Answer

It seems that at least in the current version (1.8.9) line numbers are added:

Details

Python code formatter

Python code formatter includes line numbers if g_sourceFileDef evaluates as TRUE:

/*! start a new line of code, inserting a line number if g_sourceFileDef
 * is TRUE. If a definition starts at the current line, then the line
 * number is linked to the documentation of that definition.
 */
static void startCodeLine()
{
  //if (g_currentFontClass) { g_code->endFontClass(); }
  if (g_sourceFileDef)

( https://github.com/doxygen/doxygen/blob/Release_1_8_9/src/pycode.l#L356 )

It's initialized from FileDef *fd passed into parseCode/parsePythonCode if it was provided (non-zero) or from new FileDef(<...>) otherwise:

g_sourceFileDef = fd;
<...>
if (fd==0)
{
  // create a dummy filedef for the example
  g_sourceFileDef = new FileDef("",(exName?exName:"generated"));
  cleanupSourceDef = TRUE;
}

( https://github.com/doxygen/doxygen/blob/Release_1_8_9/src/pycode.l#L1458 ) so it seems all Python code is having line numbers included

C code formatter

C code formatter has an additional variable g_lineNumbers and includes line numbers if both g_sourceFileDef and g_lineNumbers evaluate as TRUE:

/*! start a new line of code, inserting a line number if g_sourceFileDef
 * is TRUE. If a definition starts at the current line, then the line
 * number is linked to the documentation of that definition.
 */
static void startCodeLine()
{
  //if (g_currentFontClass) { g_code->endFontClass(); }
  if (g_sourceFileDef && g_lineNumbers)

( https://github.com/doxygen/doxygen/blob/Release_1_8_9/src/code.l#L486 )

They are initialized in the following way:

g_sourceFileDef = fd;
g_lineNumbers = fd!=0 && showLineNumbers;
<...>
if (fd==0)
{
  // create a dummy filedef for the example
  g_sourceFileDef = new FileDef("",(exName?exName:"generated"));
  cleanupSourceDef = TRUE;
}

( https://github.com/doxygen/doxygen/blob/Release_1_8_9/src/code.l#L3623 )

Note that g_lineNumbers remains FALSE if provided fd value was 0

HtmlDocVisitor

Among parseCode calls in HtmlDocVisitor::visit there is only one (for DocInclude::IncWithLines, what corresponds to \includelineno) which passes non-zero fd: https://github.com/doxygen/doxygen/blob/Release_1_8_9/src/htmldocvisitor.cpp#L540 so this seems to be the only command which will result in line numbers included into C code listing