Issue 69082 - autodoc strips all content after a @see tag
Summary: autodoc strips all content after a @see tag
Status: CLOSED FIXED
Alias: None
Product: Build Tools
Classification: Code
Component: autodoc (show other issues)
Version: 680m181
Hardware: All All
: P3 Trivial (vote)
Target Milestone: OOo 2.1
Assignee: nikolai.pretzell
QA Contact: issues@tools
URL:
Keywords: regression
Depends on:
Blocks:
 
Reported: 2006-08-30 08:38 UTC by Frank Schönheit
Modified: 2007-04-27 17:10 UTC (History)
2 users (show)

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


Attachments

Note You need to log in before you can comment on or make changes to this issue.
Description Frank Schönheit 2006-08-30 08:38:25 UTC
Compare
http://api.openoffice.org/docs/common/ref/com/sun/star/sdb/RowSet.html
with
http://api.openoffice.org/source/browse/api/offapi/com/sun/star/sdb/RowSet.idl?rev=1.20&only_with_tag=OpenOffice_2_0_3&view=markup

In the RowSet.idl file, there is an *extensive* documentation for the class as a
whole. However, as you can see in the online IDL reference, nearly *all* of this
documentation is simply not available.

Playing around reveals that autodoc seems to strip all content in the current
comment block after it encountered the first block of @see tags - which
certainly is not desired.
Comment 1 Frank Schönheit 2006-08-30 08:44:16 UTC
This is a regression, it used to work previously. Compare revisions 1.5 and 1.6
of RowSet.html:
http://api.openoffice.org/source/browse/api/www/docs/common/ref/com/sun/star/sdb/RowSet.html?rev=1.6&view=markup
http://api.openoffice.org/source/browse/api/www/docs/common/ref/com/sun/star/sdb/RowSet.html?rev=1.5&view=markup

I assume that's a side effect of consolidating the "Ses Also" information into
one instead of multiple paragraphs.

I consider this a blocker for the IDL reference to be put online for 2.0.4 - I
use @see quite often in various contexts, and the current behaviour simply
strips a lot of useful information in various places.
Comment 2 nikolai.pretzell 2006-09-04 10:43:25 UTC
One cannot continue the "description" of an elements docu after the first @-tag.
In Rev 1.5 of the above example, the following text is part of the @see tag, not
of the description. 

The previous use of @see tags was not according to documentation:
http://api.openoffice.org/docs/DevelopersGuide/Appendix/IDLDocumentationGuide/IDLDocumentationGuide.xhtml#1_3_1_3__40-Tagged_Part

However, I see that in that same document the @see-tag allows further
documentation. This is indeed not preserved by the "consolidated" @see tags.

So the situation seems to be: 
1. @see-tag needs a fix in Autodoc to allow further comments within the tag.
2. Use of @see in the middle of a description is wrong and those documentation
should be changed.
Comment 3 nikolai.pretzell 2006-09-12 18:22:42 UTC
Now, @see tags without additional tags are combined into one output-paragraph.
@sees with additional text get an extra paragraph.
Comment 4 nikolai.pretzell 2006-09-12 18:23:31 UTC
.
Comment 5 nikolai.pretzell 2006-09-14 14:37:30 UTC
verified
Comment 6 Martin Hollmichel 2006-09-15 11:18:21 UTC
set target to 2.1
Comment 7 nikolai.pretzell 2007-04-27 17:10:04 UTC
has been integrated into m185.