Bug 69306 - API doc: multi-paragraph parameter descriptions not supported anymore?
Summary: API doc: multi-paragraph parameter descriptions not supported anymore?
Status: RESOLVED WORKSFORME
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: sdk (show other bugs)
Version:
(earliest affected)
4.2.0.0.alpha0+ Master
Hardware: Other All
: medium normal
Assignee: Not Assigned
URL:
Whiteboard: target:4.3.0 target:4.2.0.1
Keywords:
Depends on:
Blocks:
 
Reported: 2013-09-13 08:30 UTC by Lionel Elie Mamane
Modified: 2014-08-15 13:48 UTC (History)
2 users (show)

See Also:
Crash report or crash signature:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Lionel Elie Mamane 2013-09-13 08:30:28 UTC
Compare the blurb about keepFieldsAlive in
http://api.libreoffice.org/docs/idl/ref/interfacecom_1_1sun_1_1star_1_1sdb_1_1tools_1_1XConnectionTools.html#ab96cfd3f9e8facbd9ebe98aa41a684fd
and the blurb about _rxCollectionOner (sic!) in
http://www.openoffice.org/api/docs/common/ref/com/sun/star/sdb/tools/XConnectionTools.html#getFieldsByCommandDescriptor

In the new doxygen output, the second and third paragraph are not indented correctly.
Comment 1 Michael Stahl (allotropia) 2013-09-13 16:00:18 UTC
yes there are likely still some problems where the comments are interpreted in an unintended way by doxygen but i'd prefer it if you just fix such instances when you find them instead of filing bugs about them :)
can rebuild quickly with "touch odk/docs/idl/Doxyfile && make odk"
Comment 2 Lionel Elie Mamane 2013-09-15 12:33:42 UTC
(In reply to comment #1)
> yes there are likely still some problems where the comments are interpreted
> in an unintended way by doxygen but i'd prefer it if you just fix such
> instances when you find them instead of filing bugs about them :)
> can rebuild quickly with "touch odk/docs/idl/Doxyfile && make odk"

I understood it as a bug in doxygen's IDL format support.

You seem to suggest we should change the .idl files instead.
If this is the case, sure, I'll be happy to "just fix" the
issues I find, but I don't have a clue what I'm supposed to
do in the .idl file to fix this one.
Comment 3 Jean-Baptiste Faure 2013-12-07 19:38:57 UTC
From comments #1 and #2 I understand that the bug is confirmed. So set status accordingly.

Best regards. JBF
Comment 4 Lionel Elie Mamane 2013-12-07 19:42:30 UTC
@michael stahl: how can I "fix" the idl to use multiple paragraphs indented correctly?
Comment 5 Michael Stahl (allotropia) 2013-12-10 21:29:40 UTC
sorry, this one went out of sight...

(In reply to comment #2)
> 
> I understood it as a bug in doxygen's IDL format support.
> 

well... there is no doxygen UNO IDL *comment* support,
only doxygen UNO IDL *syntax* support.

(or i guess i should say autodoc comment support, since as
far as UNO IDL is concerned comments start with /* and end with */)

the documentation for @param is here:

http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdparam

... and it speaks of "a paragraph" so probably that means one.

paragraphs breaks are indicated by an empty line, see:

http://www.stack.nl/~dimitri/doxygen/manual/markdown.html#md_para

... but fortunately we can insert a line break in the paragraph
via the <br> tag because doxygen understands HTML too:

http://www.stack.nl/~dimitri/doxygen/manual/htmlcmds.html

... and for the XConnectionTools that basically means removing the
2 empty lines gives the desired layout.

[ i wonder how long it takes until i start complaining that our IDL
comments have become inconsistent mess of JavaDoc, HTML and Markdown :D ]

not sure if all of this means the bug can be resolved - WFM perhaps?
Comment 6 Commit Notification 2013-12-10 21:30:56 UTC
Michael Stahl committed a patch related to this issue.
It has been pushed to "master":

http://cgit.freedesktop.org/libreoffice/core/commit/?id=cfb58670f13befd738eff485349894ae504200f0

offapi: fdo#69306 tweak multi-paragraph parameter comment



The patch should be included in the daily builds available at
http://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More
information about daily builds can be found at:
http://wiki.documentfoundation.org/Testing_Daily_Builds
Affected users are encouraged to test the fix and report feedback.
Comment 7 Commit Notification 2013-12-10 21:32:14 UTC
Michael Stahl committed a patch related to this issue.
It has been pushed to "libreoffice-4-2":

http://cgit.freedesktop.org/libreoffice/core/commit/?id=8fb8a39eb2c27bb5bc38601469969230f7f90c13&h=libreoffice-4-2

offapi: fdo#69306 tweak multi-paragraph parameter comment


It will be available in LibreOffice 4.2.

The patch should be included in the daily builds available at
http://dev-builds.libreoffice.org/daily/ in the next 24-48 hours. More
information about daily builds can be found at:
http://wiki.documentfoundation.org/Testing_Daily_Builds
Affected users are encouraged to test the fix and report feedback.
Comment 8 Michael Stahl (allotropia) 2014-08-15 13:48:26 UTC
no feedback so resolving WFM now