Apache OpenOffice (AOO) Bugzilla – Issue 106434
autodoc loses/ignores nearly all @see tags
Last modified: 2010-06-28 15:51:08 UTC
Looking into the output tree of a OOO320.m2 build, in module odk: > cd unxlngi6.pro/bin/odkcommon/idl/com/sun/star/sdb > grep "@see" * | wc -l 99 > cd ../../../../../docs/common/ref/com/sun/star/sdb > grep "See also" * | wc -l 7 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.
Created attachment 65759 [details] sample IDL file
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.
> While I know should have been "While I do not know" ...
So far, I could see, that this has been broken between Dev300.m32 and m57. I'll have a look what may be wrong.
fixed
np->fs: Please verify.
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: RowChangeEvent <hr>Notifications</hr> ... <table> | ... | ... | | 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.
re-opening, see above for a justification
np->fs: 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.
np->fs for verifying.
okay, old behavior restored. Whether this behavior can be improved is a separate discussion ...
close issue.