[Doxygen-develop] documentation of member classes defined outside class

[Robbie G. <ro...@m8...>]

Hi All,
  If i have code where member classes are defined outside their
containing class, like

/** Class X doco */
{
  /** Class Y doco */
  class Y;
};

class X::Y
{
};

then, afaics, doxygen doesn't pick up the doco at the declaration of
class Y - one needs to do it at the definition viz:

{
  /** Class Y doco */
  class Y;
};

/** Class X doco */
class X::Y
{
};

It seems that the versions i'm looking at are discarded as forward
declarations, around line 4306 of scanner.l (1.5.5 sources). I can
easily add a warning so i can pick up the cases where we do this and
move the documentation to the definition.

    if (!current->doc.isEmpty() || !current->brief.isEmpty())
    {
        warn(yyFileName, yyLineNr, "Warning: Ignoring documentation on
forward declaration");
    }

just before current->reset(), but i'd be interested in pointers about
the "right" way to arrange for this documentation to just get merged -
i.e. to effectively fake an @class yytext at that point. Is it
legitimate to just do what handleClass (in commentscan.l) would have
done, that is, something like

    current->section = Entry::CLASSDOC_SEC;
    current->name = yytext;
    current->name.remove(current->name.length() - 1, 1);
    prependScope();
    newEntry();

or am i missing a subtlety here ? I realise it also incorporates
documentation for forward declarations, but this doesn't seem terrible
afaics.

I should add i've tried both of these (i.e. warning, and faking the
@class block as described), and they appear to work - i just want to
check i'm not missing something important.  If its all good, i'll
clean it up and send patches.

If both declaration and definition are given, these are merged. I
wonder if its possible to warn about this, as if you're not aware its
happening, you tend to get suboptimal documentation (with things
repeated, etc).

 - robbie