Feature request: verbatim documentation comments in XML output

[jskene]

Hi,

I'm writing a documentation generator that uses the XML output from doxygen.

The format of the documentation comments that I want to process is a
nonstandard variant of markdown.

I can parse this markdown variant with my own parser. However, to do so
successfully from doxygen XML requires:

1. that doxygen does not parse documentation comments as markdown, as the
   nonstandard structure of my comments confuses it; I can accomplish this
   by specifying MARKDOWN_SUPPORT = NO; and

2. that the line structure of documentation comments in the XML output is
   otherwise largely preserved.

The second requirement is a source of difficulty, as the XML output eliminates
line breaks in comment output, replacing them with spaces.

As a workaround, I have been using a rebuilt version of doxygen, with a very
minor modification to xmldocvisitor.cpp. The function to output whitespace
normally looks like this:

void XmlDocVisitor::operator()(const DocWhiteSpace &w)
{
  if (m_hide) return;
  if (m_insidePre)
  {
    m_t << w.chars();
  }
  else
  {
    m_t << " ";
  }
}

My version looks like this:

void XmlDocVisitor::operator()(const DocWhiteSpace &w)
{
  if (m_hide) return;
  m_t << w.chars();
}

It seems to me that having an option to allow doxygen to emit code comments in
a more-or-less verbatim format as part of the XML output is a feature that
others beside myself could benefit from.

Certainly an option to not convert whitespace, or alternatively to emit an XML
element from which the original whitespace could be reconstructed, would not be
too hard to implement, as I think my hack demonstrates.

I am conscious that even with MARKDOWN_SUPPORT = NO specified, some level of
overall parsing of documentation comments takes place. For example, text
is still parsed into <para> and <itemizedlist> elements. Also, <ref>
elements identify symbols for which links might be generated.

Although I can certainly tolerate this, some of this parsing is helpful - the
<ref> elements, for example - and some unhelpful or unnecessary - breaking
the text into paragraphs and lists would be better left to my markdown
processor. An absolutely ideal 'pass-through' feature for the XML output would
I think only insert XML where doxygen is in some sense providing a
'value-added' service, such as with the <ref> tags, or text (which may
include XML structure) inserted by actual doxygen commands like @param.

Thanks a lot,
James Skene
[email protected]

[albert-github]

You wrote:

... I want to process is a nonstandard variant of markdown.

I can parse this markdown variant with my own parser.

Can you give an example so:

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).
• Please also specify the full doxygen version used (doxygen -v).
• is there a description of this non standard version?

In doxygen there is the command \xmlonly, did you have a look at it? or is this unsuitable as it does not process the, in your case, markdown parts?

[jskene]

Hi,

My modified version of doxygen has the version number 1.11.0 (cbb48edb43715e3420a69d69c21e6e3c4f998894*).

My nonstandard variant of markdown does have a specification, but it is complex. I will be publishing it and my markdown processor (implemented in C++) later this year. However, I think it is outside the scope of this feature request to expect doxygen to change the way it processes markdown for my benefit! The essence of this feature request is that different ways of parsing documentation comments can be implemented as long as sufficient information about how they were originally formatted is preserved in the XML output.

Using \xmlonly might allow me to include verbatim parts of documentation comments in the output. However, it has two significant drawbacks that I think means this is not a feasible general approach to my problem.

First, I would have to include it in every comment! (Or at least any where I suspect doxygen's markdown processing might fail.) Not only would this be inconvenient, but it would defeat the point of this exercise, which is to have nice looking documentation comments.

Second, and I haven't verified this, but I suspect that it might suppress otherwise helpful processing inside the \xmlonly block, such as the insertion of <ref> elements.

Thanks,
James