Difference between revisions of "Documentation/DevGuide/WritingUNO/Using Comments"
From Apache OpenOffice Wiki
< Documentation | DevGuide
OOoWikiBot (Talk | contribs) m (FINAL VERSION FOR L10N) |
|||
| Line 9: | Line 9: | ||
{{DISPLAYTITLE:Using Comments}} | {{DISPLAYTITLE:Using Comments}} | ||
Comments are code sections ignored by ''idlc''. In UNOIDL, use C++ style comments. A double slash <code>//</code> marks the rest of the line as comment. Text enclosed between <code>/*</code> and <code>*/</code> is a comment that may span over multiple lines. | Comments are code sections ignored by ''idlc''. In UNOIDL, use C++ style comments. A double slash <code>//</code> marks the rest of the line as comment. Text enclosed between <code>/*</code> and <code>*/</code> is a comment that may span over multiple lines. | ||
| − | < | + | <syntaxhighlight lang="idl"> |
service ImageShrink | service ImageShrink | ||
{ | { | ||
| Line 20: | Line 20: | ||
*/ | */ | ||
}; | }; | ||
| − | </ | + | </syntaxhighlight> |
Based on the above, there are documentation comments that are extracted when idl files are processed with ''autodoc'', the UNOIDL documentation generator. Instead of writing <code>/*</code> or <code>//</code> to mark a plain comment, write <code>/**</code> or <code>///</code> to create a documentation comment. | Based on the above, there are documentation comments that are extracted when idl files are processed with ''autodoc'', the UNOIDL documentation generator. Instead of writing <code>/*</code> or <code>//</code> to mark a plain comment, write <code>/**</code> or <code>///</code> to create a documentation comment. | ||
| − | < | + | <syntaxhighlight lang="idl"> |
/** Don't repeat asterisks within multiple line comments, | /** Don't repeat asterisks within multiple line comments, | ||
* <- as shown here | * <- as shown here | ||
| Line 29: | Line 29: | ||
/// Don't write multiple line documentation comments using triple slashes, | /// Don't write multiple line documentation comments using triple slashes, | ||
/// since only this last line will make it into the documentation | /// since only this last line will make it into the documentation | ||
| − | </ | + | </syntaxhighlight> |
Our <code>XUnoUrlResolver</code> sample idl file contains plain comments and documentation comments. | Our <code>XUnoUrlResolver</code> sample idl file contains plain comments and documentation comments. | ||
| − | < | + | <syntaxhighlight lang="idl"> |
/** service <type scope="com::sun::star::bridge">UnoUrlResolver</type> | /** service <type scope="com::sun::star::bridge">UnoUrlResolver</type> | ||
implements this interface. | implements this interface. | ||
| Line 43: | Line 43: | ||
... | ... | ||
} | } | ||
| − | </ | + | </syntaxhighlight> |
Note the additional <code><type/></code> tag in the documentation comment pointing out that the service <code>UnoUrlResolver</code> implements the interface <code>XUnoUrlResolver</code>. This tag becomes a hyperlink in HTML documentation generated from this file. The chapter [[Documentation/DevGuide/AppendixB/IDL Documentation Guidelines|IDL Documentation Guidelines]] provides a comprehensive description for UNOIDL documentation comments. | Note the additional <code><type/></code> tag in the documentation comment pointing out that the service <code>UnoUrlResolver</code> implements the interface <code>XUnoUrlResolver</code>. This tag becomes a hyperlink in HTML documentation generated from this file. The chapter [[Documentation/DevGuide/AppendixB/IDL Documentation Guidelines|IDL Documentation Guidelines]] provides a comprehensive description for UNOIDL documentation comments. | ||
Latest revision as of 16:28, 23 December 2020
Comments are code sections ignored by idlc. In UNOIDL, use C++ style comments. A double slash // marks the rest of the line as comment. Text enclosed between /* and */ is a comment that may span over multiple lines.
service ImageShrink { // the following lines define interfaces: interface org::openoffice::test::XImageShrink; // our home-grown interface interface com::sun::star::document::XFilter; /* we could reference other interfaces, services and properties here. However, the keywords uses and needs are deprecated */ };
Based on the above, there are documentation comments that are extracted when idl files are processed with autodoc, the UNOIDL documentation generator. Instead of writing /* or // to mark a plain comment, write /** or /// to create a documentation comment.
/** Don't repeat asterisks within multiple line comments, * <- as shown here */ /// Don't write multiple line documentation comments using triple slashes, /// since only this last line will make it into the documentation
Our XUnoUrlResolver sample idl file contains plain comments and documentation comments.
/** service <type scope="com::sun::star::bridge">UnoUrlResolver</type> implements this interface. */ interface XUnoUrlResolver: com::sun::star::uno::XInterface { // method com::sun::star::bridge::XUnoUrlResolver::resolve /** resolves an object, on the UNO URL. */ ... }
Note the additional <type/> tag in the documentation comment pointing out that the service UnoUrlResolver implements the interface XUnoUrlResolver. This tag becomes a hyperlink in HTML documentation generated from this file. The chapter IDL Documentation Guidelines provides a comprehensive description for UNOIDL documentation comments.
| Content on this page is licensed under the Public Documentation License (PDL). |
