Issue 106434 - autodoc loses/ignores nearly all @see tags
Summary: autodoc loses/ignores nearly all @see tags
Alias: None
Product: Build Tools
Classification: Code
Component: autodoc (show other issues)
Version: DEV300m61
Hardware: All All
: P2 Trivial (vote)
Target Milestone: OOo 3.2
Assignee: Frank Schönheit
QA Contact: issues@tools
Depends on:
Blocks: 99999
  Show dependency tree
Reported: 2009-10-29 13:29 UTC by Frank Schönheit
Modified: 2010-06-28 15:51 UTC (History)
2 users (show)

See Also:
Issue Type: DEFECT
Latest Confirmation in: ---
Developer Difficulty: ---

sample IDL file (2.06 KB, text/plain)
2009-10-29 13:30 UTC, Frank Schönheit
no flags Details

Note You need to log in before you can comment on or make changes to this issue.
Description Frank Schönheit 2009-10-29 13:29:45 UTC
Looking into the output tree of a OOO320.m2 build, in module odk:
  > cd
  > grep "@see" * | wc -l
  > cd ../../../../../docs/common/ref/com/sun/star/sdb
  > grep "See also" * | wc -l

This means that out of the 99 see tags in all the files in css.sdb, only 7 have
been properly recognized and transferred to the HTML file. In other modules, the
ratio is much worse, for instance, in css.util, there are 90 @see tags in the
IDL files, but only 1 (!) in the generated HTML documentation.

I know that in the past, it has been said that @see tags are not supported in
every place within the documentation. While I know whether this still holds (I
hope it doesn't), the current situation is certainly wrong.
Comment 1 Frank Schönheit 2009-10-29 13:30:26 UTC
Created attachment 65759 [details]
sample IDL file
Comment 2 Frank Schönheit 2009-10-29 13:35:44 UTC
The attached file illustrates the problem (or at least parts of it): Place it in
offapi/com/sun/star/sdb, and run autodoc: The see-tags for the global entity and
for the first member are ignored by autodoc, though there's nothing fancy there,
they're most straight-forward.

Only the tag for the second member is respected, here the difference seems to be
thatt the tag is followed by additional text. However, the following text is
(wrongly) put below the "See also" item in the HTML file, so even here, autodoc
is not completely right

Nominating as 3.2 stopper. I do not think we should release an API documentation
in this state.
Comment 3 Frank Schönheit 2009-10-29 13:41:24 UTC
> While I know

should have been "While I do not know" ...
Comment 4 nikolai.pretzell 2009-10-29 16:11:55 UTC
So far, I could see, that this has been broken between Dev300.m32 and m57. 
I'll have a look what may be wrong.
Comment 5 nikolai.pretzell 2009-11-04 12:49:59 UTC
Comment 6 nikolai.pretzell 2009-11-04 13:18:59 UTC
np->fs: Please verify.
Comment 7 Frank Schönheit 2009-11-05 10:46:35 UTC
fs->np: Sorry, not yet there. Compare css/sdb./owSet.idl with the generated
css/sdb/RowSet.html: In the latter, the structure is something like this:

  See also:
    RowChangeAction, ResultSet
  See also:
    | ... | ...
    |     | See also:
    |     |    XColumnsSupplier

There are two bugs here:

First, I would not expect "Notifications" to appear below the "See also" item,
it semantically surely doesn't belong there (and also in the IDL, it is clearly
separated by a </p>.

Second, the ResultSet does belong to the XColumnsSupplier. That is, in the IDL,
there's a
  @see ResultSet
  @see com::sun::star::sdbcx::XColumnsSupplier
in the table cell in question, that is, both see-tags belong together. In the
HTML file, one of those two is moved to a completely different location,
corrupting the meaning this way.
Comment 8 Frank Schönheit 2009-11-05 10:46:54 UTC
re-opening, see above for a justification
Comment 9 nikolai.pretzell 2009-11-05 11:19:51 UTC
This is the intended behaviour. Any @see Tag 1. finishes the Description (if we
were there stil), and 2. starts a new paragraph. So all text below the first
@see tag in RowSet.idl is understood as a comment to the last previous @see tag.
So RowSet.idl should use @see only after the description.

That the structure still looks rather similar to the original is because in HTML
tables override other structures like paragraphs.

We should discuss wishes for changed behaviour separately. The bug should be
fixed by this.
Comment 10 nikolai.pretzell 2009-11-05 11:20:46 UTC
np->fs for verifying.
Comment 11 Frank Schönheit 2009-11-05 11:28:40 UTC
okay, old behavior restored. Whether this behavior can be improved is a separate
discussion ...
Comment 12 Martin Hollmichel 2010-06-28 15:51:08 UTC
close issue.