Difference between revisions of "Documentation/DevGuide/WritingUNO/Using Comments"
m (1 revision(s)) |
m |
||
Line 8: | Line 8: | ||
{{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. | ||
− | + | <source lang="idl"> | |
service ImageShrink | service ImageShrink | ||
{ | { | ||
Line 19: | Line 19: | ||
*/ | */ | ||
}; | }; | ||
− | + | </source> | |
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. | ||
− | + | <source 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 28: | Line 28: | ||
/// 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 | ||
− | + | </source> | |
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. | ||
− | + | <source 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 42: | Line 42: | ||
... | ... | ||
} | } | ||
− | + | </source> | |
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. | ||
{{PDL1}} | {{PDL1}} | ||
[[Category: Writing UNO Components]] | [[Category: Writing UNO Components]] |
Revision as of 19:54, 21 March 2008
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). |