Using Comments

From Apache OpenOffice Wiki
Jump to: navigation, search



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).
Personal tools
In other languages