Child pages
  • Documenting the Plugin API

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Documenting The API

Servoy supplies a Java Eclipse Documentation Generator plugin to help with documenting the plugin API.

This plugin allows to transform your the plugin JavaDoc into a Servoy plugin xml api file, the . The generated XML file needs to be bundled with the plugin. Which , which then will be used in Servoy Developer to provide the information (namely, the documentation) to the developer using the plugin.

All the relevant API information can be supplied by JavaDoc directly on the public methods and properties of the plugin.

The IScriptable Interface

The IScriptable interface is an empty interface that classes that expose methods or properties to the JavaScript layer in Servoy have to implement. When plugins get loaded in Servoy Developer, for all classes that implement documentation provided in the classes implementing this interface , the documentation will be loaded. For more information refer to the IScriptable API doc in the Servoy API.

The IScriptable interface replaces three methods of the IScriptObject interface previously used to provide documentation for plugin methods and properties: getSample, getToolTip, getParameterNames.

The . getAllReturnedTypes() method of the deprecated IScriptObject is replaced by separate interface IReturnedTypesProvider, which only needs to be implemented on plugin classes that have actual returnTypes.

Documenting Method & Properties Using JavaDoc

When implementing the new documentation mechanism, the method sample code, tooltip, parameter names will have to be documented using JavaDoc. For more details on writing documentation in the Javadoc way, see the Javadoc reference pages. This type of code documentation is a standard way of documenting Java code.

...

A plugin must annotate itself so that the Document Generator Tool knows what to get. Servoy has a special annotation called @ServoyDocumented. The annotation can have additional attributes to specify the public and scripting names. Below, is a sample of the FilePlugin:

...

For returnTypes like JSFile the the @ServoyDocumented annotation marks a class for documentation:

...

Note that if a class is documented, documented methods/properties will be looked up in the class hierarchy. If a method is present multiple times in hierarchy, the first occurance occurrence will be used by doc generator.

...

If a method is annotated with the special annotation @JSReadOnlyProperty, it will bee considered a readonly property of the plugin.

Code Block
/**
 * This is a readonly property
 */
@JSReadOnlyProperty
public String myPropertyVersion()
{
     return "version 1.0";
}

Two methods using the the @JSGetter and and @JSSetter properties can be used to create a property of the plugin, as follows:

...

If a method is annotated with the the @JSFunction property it will be considered a JavaScript function:

Code Block
@JSFunction
public String myFunction(String myParameter)
{
     //...
}

Please note Note that the method above does not have to start with the 'the js_' prefix in order to be considered a JavaScript function of the plugin it belongs to.

If a method should be marked as deprecated, the new documentation generator tool also takes into consideration the the @Deprecated annotation:

Code Block
@Deprecated
public void neverRetire()
{
     //...
}

...

Besides the standard JavaDoc tags like @param, @return and @since, Servoy introduces a few tags to provide sample code part or to clone parts of the JavaDoc ofanother of another method.

  • @sample: doc below this section, until the next tag is seen as sample code. This should contain the text previously returned by .by getSample(String methodName)
  • @sampleas: this will copy over the sample code from another method: @sampleas js_someMethod(String)
  • @clonedesc: this will copy over the description from another method: @clonedesc js_someMethod(String)
  • @sameas: this will copy the entire documentation from another method: @sameas js_someMethod(String)

The The @param tag supports so-called rest parameters by using  'using  ...' prefix. It also supports marking parameters as optional. The following example is the button a optional and variable arguments parameter.

Code Block
 @param ...button optional

If you want to use a JSDoc notation in your sample code for example To be able to type a specific variable, so like /** @type {JSFile} */. Then , using a JSDoc annotation, the last / slash must be escaped by using the ascii ASCII notation:

Code Block
 /** @type {JSFile} */

The Documentation Generator Tool

After annotating the source of the plugin using JavaDoc, the documentation needs to be exported to XML format and bundled with the plugin. Servoy provides a an Eclipse plugin to generate the XML, called the Documentation Generator.

In order to have the method documentation available , in JavaScript, you must the documentation generation tool needs to be installed , in the Eclipse in which you are developing the plugin code (along with its documentation)is being developed. The documentation generation tool must be installed via Eclipse update sites. From the Servoy Developer, via Go to Help > Install New Software..., add the http://www.servoy.com/documentbuilder url as an update site URL and install the documentation generator (Servoy Documentation Generator Feature). It will show up under installed software as the Servoy Documentation Generator Feature.

Note
titleNote

You might need to have 'Note that Group items by category' has to be unchecked in the install new software Install New Software first wizard page.

After the tool is installed, you can generate the documentation of a the plugin , can be generated by selecting the project/package corresponding to that plugin and using the context menu Servoy > Generate Servoy Documentation XML. An A file with the plugin's documentation, available in XML format, will be generated.

...

The documentation generator tool also has a corresponding preference page, which will show up in Eclipse up under Windows > Preferences > Servoy Documentation Generator. There are currently two properties which can be set:

...