Introspector documentation needs improvement

[jlouvel]

The Javadoc page of the Introspector is here: http://restlet.com/technical-resources/restlet-framework/javadocs/2.3/jse/ext/org/restlet/ext/apispark/Introspector.html

This page doesn't contain any information on the parameters supported by the Introspector program. Also, it doesn't include an hyperlink to the dedicated page in the User Guide which is: https://restlet.com/technical-resources/restlet-framework/guide/2.3/extensions/apispark/introspector

Also, here is the output of the built-in help with some modifications suggestions included. You actually have to run the tool with --help parameter to see the details.

SYNOPSIS
       org.restlet.ext.apispark.Introspector [credentials] [actions] [options] [--language
       swagger SWAGGER_DEFINITION_URL_OR_PATH | APPLICATION]

DESCRIPTION
       Publish to the APISpark platform the description of your Web API, represented by
       APPLICATION, the full name of your Restlet or JAX-RS application class or by the Swagger
       definition available at URL/PATH
       If the whole process is successful, it displays the url of the corresponding descriptor or
       connector cell.

EXAMPLES
       org.restlet.ext.apispark.Introspector -u 1234 -p Xy12 --create-descriptor
       com.acme.Application
       org.restlet.ext.apispark.Introspector -u 1234 -p Xy12 --new-version --id 60
       com.acme.Application
       org.restlet.ext.apispark.Introspector -u 1234 -p Xy12 --update --update-strategy replace
       --id 60 --version 1 --language swagger http://acme.com/api/swagger

OPTIONS
       -h, --help Prints this help.

       [credentials]
       -u, --username username
              The mandatory user name available from the Tokens section of your APISpark Account page.
       -p, --password password
              The mandatory secret key available from the Tokens section of your APISpark Account page.

       [actions]
       -d, --create-descriptor
              Creates a new API Descriptor in APISpark based on the introspection result.
       -c, --create-connector
              Creates a new API Connector in APISpark based on the introspection result.
       -n, --new-version
              Creates a new major version of the APISpark cell identified by the -i (--id) option
       -U, --update
              Updates the APISpark cell identified specified by the -i (--id) and -v (--version)
              options. Uses the default update strategy (update) except if -S (--update-strategy)
              option is specified.

       [options]
       -i, --id cellId
              The identifier of an existing APISpark cell (API Descriptor or Connector) that you want
              to update. Required if -n (--new-version) or -U (--update) options are specified.
       -v, --version cellVersion
              The major version of the cell to be updated.
              Required if -U (--update) option is specified.
       -s, --update-strategy strategy
              Specifies the update strategy. Available strategies:
              - update: (default) new elements will be added to the APISpark cell,
              primitive fields of existing objects will be updated. Nothing will be deleted.
              - replace: deletes all the information in the APISpark cell
              and fills it again with introspected definition.
       --component componentClass
              The optional full name of your Restlet Component class. This allows to collect 
              additional metadata, such as the endpoint.
       -l, --language languageName
              The optional name of the description language of the definition you want to upload.
              Possible value:
              - swagger: Swagger 1.2 specification.
       --sections
              Set section of introspected resources from Java package name.
       -v, --verbose
              The optional parameter switching the process to a verbose mode

ENHANCE INTROSPECTION
       You can extend the basic introspection and enrich the generated documentation by providing
       dedicated helpers to the introspector. By default, Swagger annotation are supported.
       Introspection use the Java Service Loader system. To add a new helper, create a
       'META-INF/services/org.restlet.ext.apispark.internal.introspection.IntrospectionHelper' file
       with the name of your implementation class.