[PATCH] Documentation parsing: allow some commands to have multiple paragraphs attached

[Dmitri Gribenko]

Hello,

Fariborz and I would like to propose a change to our current comment parsing
model to allow multi-paragraph parameter and return value descriptions.

Please take a look and tell what you think.

Motivation
==========

Case 1
------

/// \param x1 Aaa.
/// Aaa. Aaa.
///
/// Bbb.
///
/// \param x2 Ccc.
void doSomething(int x1, int x2);

In this case, the user most likely intended "Bbb" to be a second paragraph of
the \param x1.  But our current parsing model only allows a single paragraph to
be attached to a block command, so we treat "Bbb" as a part of *function
description*.  Because this is the first paragraph of the function description,
"Bbb" also becomes the brief description.

Case 2
------

/// \returns
/// \li Foo, or
/// \li EnchancedFoo.
Foo *makeFoo();

In this case, \returns and \li are block commands, so \returns has an empty
paragraph, and \li points are separate from \returns and become a part of the
function description.  Furthermore, "Foo, or" becomes the brief function
description.

Proposed change to parsing model
================================

\param, \tparam and \returns commands consume paragraphs and block commands
until we hit a command that is only allowed to appear at the top level.  For
example:

/// \returns Either:
/// \li Foo, or
/// \li EnchancedFoo.
/// \param isEnchanced Aaa.
Foo *makeFoo(bool isEnchanced);

Everything starting from "Either:" until "\param" -- one paragraph and two \li
commands -- become child nodes of the \returns command.  Because \param is a
top-level-only command, we stop attaching children to \returns and return to
top-level at that point.

Right now I have identified that it makes sense to allow only \li, \arg (alias
of \li), and \verbatim-like commands to be nested within other commands.  All
other block commands are top-level-only.

What comments will parse differently
====================================

Comments where the user placed the long description after parameter or return
value description will parse differently.  For example:

/// \param x1 Aaa.
///
/// This functions does...
void foo(int x1);

"This function does..." used to be a brief description, now it is the second
paragraph of parameter description.

One can get the previous behavior again by using explicit \brief or \details
commands, depending on the intent:

/// \param x1 Aaa.
///
/// \brief This function does...

How Doxygen handles this
========================

As far as I see, in its output, Doxygen preserves the sequence of paragraphs,
and it also does not try to assign semantic meaning to paragraphs.  Because of
this, Doxygen will not hit any issues regardless whether it uses the original
Clang's parsing model or this proposed model -- it does not make a differece
for the output that Doxygen produces.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: comment-parsing-allow-multiple-paragraph-args-v1.patch
Type: application/octet-stream
Size: 80805 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20131122/79cbffbc/attachment.obj>