doxygen API doc: list of uses?

[Lionel Elie Mamane]

On Wed, Sep 11, 2013 at 05:15:57PM +0200, Michael Stahl wrote:
> On 10/09/13 15:55, Lionel Elie Mamane wrote:
> > On Wed, Sep 04, 2013 at 11:56:07PM +0200, Andras Timar wrote:
> > 
> >> I updated api.libreoffice.org from master.
> > 
> > We seem to have lost the feature of e.g.
> >  http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/Date-xref.html
> > that is the list of all the places in the API where this type is used.
> 
> well i though that stuff is more easily found with "git grep" anyway so
> didn't bother to invest any time in that.

"git grep" is not obvious / easy to use for that, and possibly not
completely possible to use. Case in point:

git grep com::sun::star::util::Date
# drats, also occurrences of shows com::sun::star::util::DateTime
git grep -E 'com::sun::star::util::Date[[:space:]]'
# drats, misses com/sun/star/util/DateTimeWithTimezone.idl
( git grep -E 'com::sun::star::util::Date[[:space:]]' offapi; \
  git grep -E 'sun::star::util::Date[[:space:]]' offapi/com; \
  git grep -E 'star::util::Date[[:space:]]' offapi/com/sun; \
  git grep -E 'util::Date[[:space:]]' offapi/com/sun/star; \
  git grep -E 'Date[[:space:]]' offapi/com/sun/star/util; \
) | $PAGER
# starts to be quite complicated... and lots to type...
# need to write a wrapper script that creates the right series
# of "git grep"...
# and gives duplicates... So something like
( git grep -E 'com::sun::star::util::Date[[:space:]]' offapi; \
  git grep -E 'sun::star::util::Date[[:space:]]' offapi/com; \
  git grep -E 'star::util::Date[[:space:]]' offapi/com/sun; \
  git grep -E 'util::Date[[:space:]]' offapi/com/sun/star; \
  git grep -E 'Date[[:space:]]' offapi/com/sun/star/util; \
) | sort -u | $PAGER


And still, this solution could still have false positives!
(although this particular example does not). E.g. imagine a
 com::sun::star::sdbc::util::Date, which is referred to in
 com/sun/star/sdbc/Foo.idl as:
 [property] util::Date Bar;
it would be matched by the
  git grep -E 'util::Date[[:space:]]' offapi/com/sun/star

And still, this solution still shows matches within comments in .idl
files (this example does not show any only because all matches are at
the end of a sentence and thus are followed by a fullstop and not
space). But e.g.
 git grep -E com::sun::star::util::XCloneable'[[:space:]]'
has *five* such false positives, for only *one* true positive. Bad
score.

So, no, really, IMHO "git grep" is not a proper substitute for
doxygen's true parsing, handling of such namespacing, comments, etc.


The doxygen graphs seem to be "collapsed" when they get too big... Not
sure I like that...

Compare

  http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/XCloneable-xref.html#SupportingServices
  http://www.openoffice.org/api/docs/common/ref/com/sun/star/util/XCloneable-xref.html#Deriveds

and

  http://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1util_1_1XCloneable.html

The first shows e.g.

    ::com::sun::star::report::XReportControlModel
        ::com::sun::star::report::XFixedLine
        ::com::sun::star::report::XFixedText
        ::com::sun::star::report::XFormattedField
        ::com::sun::star::report::XImageControl
        ::com::sun::star::report::XShape
    ::com::sun::star::report::XReportDefinition

  ::com::sun::star::awt::UnoControlNumericFieldModel
  ::com::sun::star::awt::UnoControlPatternFieldModel
  ::com::sun::star::awt::UnoControlProgressBarModel
  ::com::sun::star::awt::UnoControlRadioButtonModel
  ::com::sun::star::awt::UnoControlRoadmapModel
  ::com::sun::star::awt::UnoControlScrollBarModel

But these do not appear in the doxygen graph because it is "cut" at
their parent.

>> I don't find that feature in the Doxygen output. Is it just my
>> blindness or have we "voluntarily" regressed here?

> personally i think the inheritance graphs from Doxygen are a lot more
> useful than the "Uses" pages from autodoc.

The inheritance graphs are nice, and they give about the same
information as "Derived Interfaces" and "Services which Support this
Interface" sections, with a prettier layout and with the added bonus
that the "Services which Support this Interface" part is more
structured (shows inheritance path instead of flattening it out).

*But* they do not give _at_ _all_ the information from "Uses as Return
Type", "Uses as Parameter" nor "Uses as Data Type", where as explained
above, I don't see "git grep" as a good replacement.

-- 
Lionel