Scripting Documentation API

Last modified by Thomas Mortagne on 2024/03/04 00:14

cogProvides useful helpers to generate scripting documentation
TypeJAR
CategoryAPI
Developed by

Denis Gervalle

Active Installs152
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Compatibility
  • 1.4+ requires XWiki 13.10

Installable with the Extension Manager

Description

This API is made to support the Scripting Documentation Application

The concept of this API is to provide scripting documentation by dynamically searching the current wiki instance for available bindings. Using the information from Maven pom's, those bindings get linked to their respective documentations both on the XWiki Extension Repository and the XWiki Nexus Repository that hold Javadoc packages. Primitive bindings and non maven compliant ones, like velocity variable and tools could also be documented using simple descriptions and links to documentation from a localization bundle. An initial bundle is provided with this extension. All returned information is cached for the duration of the instance to provide acceptable performance and limit the load on XWiki.org sites.

Script Service

High level feature are exposed by a ScriptService providing the following interface:

public class ScriptingDocumentationScriptService implements ScriptService
{
   /**
     * @return a list of available kinds of bindings finders.
     */

   public Collection<BindingKind> getAvailableBindingKinds();

   /**
     * @param kind the kind.
     * @return a binding kind corresponding to kind.
     */

   public BindingKind getBindingKind(String kind);

   /**
     * @return the default bindings finder.
     */

   public ScriptBindingsFinder getBindingsFinder();

   /**
     * @param kind the kind of the bindings finder to return.
     * @return the bindings finder appropriate for the given kind, null if none where found.
     */

   public ScriptBindingsFinder getBindingsFinder(BindingKind kind);

   /**
     * @return all bindings finder kinds.
     */

   private Set<String> getBindingsFinderKinds();

   /**
     * Return information about a Java type.
     * @param name the fully qualified name of the desired class.
     * @return a binding providing information about the given class or null if not found.
     * @since 1.1
     */

   public Binding getTypeInformation(String name);
}

Additionally, BindingKind type is transparently converted from String and to String.

Script Bindings Finders

Main feature of this API are provided by Script Bindings Finders which expose the following interface:

public interface ScriptBindingsFinder
{
   /**
     * @return a list of all bindings found.
     */

    List<Binding> find();

   /**
     * @param kind a binding kind.
     * @return a list of all bindings of given kind.
     */

    List<Binding> find(BindingKind kind);

   /**
     * @param name a binding name.
     * @return first bindings of given name.
     */

    Binding find(String name);

   /**
     * @param kind a binding kind.
     * @param name a binding name.
     * @return the bindings matching the given kind and name. Null if none where found.
     */

    Binding find(BindingKind kind, String name);

   /**
     * @param regex a pattern to match binding name.
     * @return a list of all bindings matching regex.
     */

    List<Binding> find(Pattern regex);

   /**
     * @param kind a binding kind.
     * @param regex a binding name.
     * @return a list of all bindings of the given kind matching regex.
     */

    List<Binding> find(BindingKind kind, Pattern regex);
}

Bindings

Finders provide access to bindings which expose this interface:

public interface Binding
{
   /**
     * @return the name of this binding. (ie: solr)
     */

    String getName();

   /**
     * @return the full name of this binding. (ie: services.solr)
     */

    String getFullName();

   /**
     * @return the type of this binding. (ie: Class<org.xwiki.search.solr.script.SolrIndexScriptService>)
     */

    Type getType();

   /**
     * @return the type of this binding. (ie: BindingKind SCRIPT_SERVICE = new BindingKind("service"))
     */

    BindingKind getKind();

   /**
     * @return true if this binding is from an internal package.
     */

   boolean isInternal();

   /**
     * @return true if this binding is deprecated.
     */

   boolean isDeprecated();

   /**
     * @return true if this binding is from a legacy package.
     */

   boolean isLegacy();

   /**
     * @return a description of this binding. Could be null.
     */

    String getDescription();

   /**
     * @return an URL pointing to the Javadoc of this binding. Could be null if no Javadoc has not been discovered.
     */

    URL getDocLink();

   /**
     * @return the binding resource that provide this binding.
     */

    BindingResource getResource();
}

Binding Resource

Bindings are provided by a Binding Resource, which in Maven terms is the equivalent of a module. The binding resource provides further information using this interface:

public interface BindingResource
{
   /**
     * @return the identifier of the resource (ie: org.xwiki.platform:xwiki-platform-search-solr-api:6.4.2).
     */

    String getId();
...
   /**
     * @return the URL of the documentation for this resource package. (ie: A link to this site pointing directly to the module)
     */

    URL getDocLink();
}

Translation bundle to provide more meta information about bindings

Actually some bindings does not provide much information and need to be complemented. The information about a bindings could be improved by providing a translation bundle containing some special translation according to this format:

scriptdoc[.internal|.deprecated].<binding kind>.<binding name>.description=<short description of the binding>

where [.internal|.deprecated] is optional and allow to mark internal or deprecated bindings; <binding kind> is the BindingKind as a string, <binding name> is the binding short name and <short description of the binding> is the description that will be returned by org.xwiki.scripting.documentation.Binding#getDescription().

scriptdoc.<binding kind>.<binding name>.docLink=<url>

where <binding kind> is the BindingKind as a string, <binding name> is the binding short name and <url> is a valid URL that will be returned by org.xwiki.scripting.documentation.Binding#getDocLink().

Here some example of these translations:

scriptdoc.script.request.description=The current request being processed.
scriptdoc.velocity.mathtool.description=Tool for performing math in Velocity.
scriptdoc.velocity.mathtool.docLink=http://velocity.apache.org/tools/devel/javadoc/org/apache/velocity/tools/generic/MathTool.html
scriptdoc.deprecated.template.blacklistedSpaces.description=(Deprecated use hidden document) Array of spaces that should be hidden.
scriptdoc.internal.template.discard.description=By convention, this temporary variable is used in Velocity to discard returned values during a function call.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Release Notes

v1.4.1

v1.4

v1.3.3

v1.3.2

v1.3.1

v1.3

v1.2

v1.1

Dependencies

Dependencies for this extension (org.xwiki.contrib.scriptingdocumentation:scripting-documentation-api 1.4.1):

Tags:
    

Get Connected