Information about OOo/URE @since tag usage for autodoc/javadoc is now
available at
<http://wiki.services.openoffice.org/wiki/UNO_%40since_Tags>. Please
remember to add appropriate @since tags whenever you add some entity to
our API.
-Stephan
Stephan Bergmann wrote:
Stephan Bergmann wrote:
[...]
1 autodoc is part of the SDK, and if we ever want to promote use of
UNO (and thus the SDK) outside a direct OOo context, the
syntactically hardwired "OOo" within "@since OOo .*" is unfortunate.
2 To be consistent with the UNOIDL and C++ comments, Java comments
will also be written as "@since OOo .*". The current SDK API
documentation talks about a "UDK 3.1.0 API Reference" (see
<http://api.openoffice.org/docs/cpp/ref/index.html> and
<http://api.openoffice.org/docs/java/ref/overview-summary.html>). It
is confusing if, for example, the "Since" texts within the "UDK 3.2.0
Java API Reference" read "Since OOo 2.0.0." instead of "Since UDK
3.2.0".
[...]
To solve problems 1 and 2, I'd suggest to do the following two changes:
- Change autodoc to replace everything after the "@since" tag
(i.e., drop the hardwired "OOo " part).
[That already got clarified; it was a misunderstanding on my part.]
- Think of a better naming scheme for @since tags within the SDK
API, that works equally well for UNOIDL/C++ (processed by autodoc
with its rewrite feature) and Java (processed by javadoc without such
a feature). The easiest solution might be to stick with "UDK 3.1.0"
etc.
After an offline discussion with Jürgen and Michael, we came to the
following conclusion:
- In the UNOIDL documentation (modules udkapi, offapi), stick with the
"@since OOo" introduced in
http://api.openoffice.org/servlets/ReadMsg?list=dev&msgNo=11171. (If we
ever want to create a free-standing UNO runtime and consider part of the
existing OOo UNO API as part of such a UNO runtime, we can then still
change the @since tags within the relevant UNOIDL files wholesale, to
reflect that they are part of a "UNO runtime" instead of "OOo.")
- In the documentation of UDK-relevant C++ and Java, use
@since UDK <MAJOR>.<MINOR>.<MICRO>
Valid combinations of <MAJOR>, <MINOR>, and <MICRO> are
- 3.0.1, corresponding to OOo 1.0.x
- 3.1.0, corresponding to OOo 1.1.x
- 3.2.0, corresponding to OOo 2.0.0
(Unfortunately, we did not assign individual MAJOR.MINOR.MICRO
combinations for the various OOo "micro" releases, even though we
occasionally added new functionality in such releases. This mistake
shall be corrected starting with OOo 2.0.0.)
This deliberately keeps an inconsistency between UNOIDL ("@since OOo")
and C++/Java ("@since UDK"): For those parts of the existing OOo UNO
API that should be considered part of a "UNO runtime" (e.g.,
com.sun.star.uno, com.sun.star.lang), it would be better to use "@since
UDK", while for those parts that should be considered part of OOo proper
(e.g., com.sun.star.document, com.sun.star.text), it would be better to
use "@since OOo". However, nobody is currently eager to divide the
existing OOo UNO API into those two parts (the division into the two
modules udkapi and offapi being an old such attempt, that probably got
blurred over time), so we better keep the status quo :)
-Stephan
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
