Service Comments Viewer

When developing services for the webMethods platform, these have in their structure fields that are comments:

Comments on the service itself;
Comments on each field in the input/output signature;
Comments on the FLOW service steps.
These are only for FLOW services and are equivalent to comments on the code of Java or other languages.

These comments are the first line of documentation of the service implementation and on what the service is intended for, how to use it, what kind of parameters are accepted and what kind of output to expect. Filling and maintaining this information is the job of the developer and should never be neglected. If this is information is rich and accurate enough it can effectively be used to generate de User Guide for using the service.

The objective of this document if to provide the developer with guidelines on what information can (and should) be placed in the aforementioned service comment fields and, with even more significance, how to format that information in ways that:

The comments are themselves more readable;
The comments field contents can be used by an automatic process from which can result an automatically generated user readable document (Service User Guide), such as a PDF.

For the purpose of the documentation intended to be produced from the service's comments, those on the service steps and source code will not be considered.

This page contains information about the current release of the Service Profiler.

Comments Composition and Processing

Comments are expected to be composed of text formatted as markdown, DocLet-like tags and xHTML constructs.

Markdown;
Markdown is a text formatting syntax and tool that resembles the formatting syntax used in WIKIs, but that is intended to be much easier to use and read. Additionally, the text formatted with markdown syntax can easily be converted to HTML. Information on the syntax of markdown can be found at http://daringfireball.net/projects/markdown/syntax.
DocLet-like tags;
DocLet tags are those that are used in the JavaDoc comments and that identify code element being commented, such as @author, @version, @since, etc. In this guide they are called DocLet-like tags because only some of these tags are being borrowed from JavaDoc, while others have been created specifically for the purpose of helping commenting the service. The list of tags and how to use them is presented further ahead in this document.
xHTML + CSS.
For an extra control of the format of the comments, xHTML and CSS can also be used in complement of the above syntaxes. Take notice, however, that markdown may restrict the interchangeable use of HTML.

The order of processing the comments into xHTML is:

First the DocLet-like tags;
Then the markdown syntax;
The resulting xHTML snippets are then combined into the final xHTML + CSS document.

Markdown

Common Pitfalls when using Markdown

When using markdown, there are some common mistakes or user assumptions that result in an unexpected result.

In this section are listed the most common cases and how to overcome them:

Intended Lists do not generate HTML <ol> or <ul>;

This is normally because you did not leave a blank line between the last line and the start of the list.

Markdown considers consecutive lines as part of the same paragraph.

To end the paragraph you need to insert a blank line, otherwise the list is considered part of the paragraph and is appended to it.

   **Incorrect**.
   What this service does (_the lines that are considered part of this paragraph_):
     1. Adds two integers and returns the result;
     2. Is a test service to demonstrate the use of **WSC**s and **WSD**s.

   **Correct**.
   What this service does:

     1. Adds two integers and returns the result;
     2. Is a test service to demonstrate the use of **WSC**s and **WSD**s.

Markdown is not being interpreted.

Note that markdown formatting syntax is not processed within block-level HTML tags. E.g., you can't use markdown-style *emphasis* inside an HTML block.

   <div>
      The markdown syntax in this tag is *not* going to be interpreted.

      For instance, it can contain a list:

         * First;
         * Second;
         * Third.

   </div>

DocLet-like tags

These tags are the first ones to be processed and are translated to xHTML constructs.

The tags usage is restricted to a single comments context:

Service;
This context refers to the comments block of the service itself.
Argument.
This context refers to comments field specific to an individual argument in the input/output signature.

**Table 1** - DocLet-like tag explanation and context usage
Tag	Context	Description
`@author <author name>`	Service	The author name is any text following the `@author` tag up until the end of the line. There may be more than one author. When that is the case, place one `@author` tag per author, each in its own text line.
`@since <version>`	Service	The version of the package when this service was first introduced. There can be only one of these tags per comment.
`@category <category>`	Service	The category name is any text following the @category tag up until the end of the line. There may be more than one category. When that is the case, place one @category tag per category, each in its one text line. The categorization of a service serves the purpose of giving further but condensed information about the service, and grouping services by their category, such as: Security; Technical Utility; General Utility; Transformation; Validation; Normalization; User Interface; etc.
`@deprecated <text>`	Service	Indicates that the service is deemed deprecated, and is not to be used anymore. The deprecation tag is accompanied by a paragraph of text giving reason for the deprecation and directions to what to use in its place. There can be only one of these tags per comment.
`@conditional`	Argument	Does not produce any HTML construct, and has no arguments. This tag indicates that the argument importance is Conditional, meaning that it is either Mandatory or Optional depending on a condition over another argument value. The explanation of the condition(s) has to be done as part of the argument comment text. An example of comment text: @conditional This field is only mandatory if `recordType` is "`D`", and the value has to be a signed integer if the `valueSign` argument is `null`. The tag has to appear in a line by itself, but it can be any line, not necessarily the first one.

Extended DocLet-like tags

The tags presented in the above section are the set of core tags anticipated for the comments processor. However, the processor also accepts the configuration of additional tags that extend the core set. The default distribution of this tool already defines a set of extended tags anticipated are shown the table below.

The extended DocLet-like tags are similar in structure and usage to the core DocLet-like tags, but have specific rules:

In their definition, they are applicable to either the Service context or the Argument context, not both;
Unlike the core tags, they can have a default value.
Core DocLet-like tags do not have default values, i.e., if it is not referenced, it does not exist.

With Extended DocLet-like tags, if a default value is defined for it, if it is not referenced in the comment it assumed it is referenced with the default value.

It is important to retain that this list of Extended DocLet-like tags can be changed and incremented at any time.

**Table 2** - *Out-of-the-box* Extended DocLet-like tag explanation and context usage
Tag	Context	Default Value	Description
`@project <project name>`	Service	none	The project name is any text following the `@project` tag up until the end of the line. It is intended to identify the project that spawned the creation of the service. There can be only one of these tags per comment.
`@security <classification>`	Service	none	The security classification is any text following the `@security` tag up until the end of the line. There can be only one of these tags per comment.

Configuring or adding an Extended DocLet-like tag

Extended DocLet-like tag are configured in the file $IS_DIR/packages.var/WiaServiceCommentsViewer/config/custom_tags.cnf.

After editing the properties file, reload the WiaServiceCommentsViewer package so that the changes are recognized.

A complete example of a new custom tag (tag names are case-sensitive and cannot contain whitespaces):

               com.wrightia.svccmmtsvuer.customtag.mytag.caption=My Tag
               com.wrightia.svccmmtsvuer.customtag.mytag.cssClassName=mytag
               com.wrightia.svccmmtsvuer.customtag.mytag.defaultValue=Any Value
               com.wrightia.svccmmtsvuer.customtag.mytag.isMultipleInstance=false
               com.wrightia.svccmmtsvuer.customtag.mytag.name=mytag

To complete the setting and enabled it, you have to manually append it to the com.wrightia.svccmmtsvuer.customtags property, like this:

               com.wrightia.svccmmtsvuer.customtags=project\=Y;security\=Y;mytag\=Y

Special Developer Comments

In any of the service or arguments comment fields, there may be information that is specifically oriented for the developers. This information can be of any nature but normally it is either for internal maintenance guidance or a changes history log.

This kind of information is not suited to show in a document that is intended for the service consumer. There must be a way of suppressing this information from the final document without forcing its removal from the service comments and even from the development cycle.

Because the final document is a rendering of an xHTML document, the xHTML/CSS rules can be used to control its behaviour. So, the suggested solution is to encapsulate this special information in an HTML DIV using the CSS class developerNote. For example:

            <div class="developerNote">
            -----------------------------------------------------------------------------------------
            Modification History

            AUTHOR                    DATE             DESCRIPTION
            ------------------------  -------------    ----------------------------------------------
            Robert A. Smith           29-JAN-2004      Correct validation of mandatory arguments.
            -----------------------------------------------------------------------------------------
            </div>

Normally, these comments are discarded from the documentation generated for the final user. However, in some situations these notes may be intended to be part of the document, but restricted to the next developer and not the service's end user.

By default, this construct is referenced in the CSS with instructions to hide it.

When shown, in the default CSS distributed with the tool, the way the developer note is rendered is dependent of the HTML construct used:

With a simple DIV, the entire block is just rendered as PRE, i.e., mono-spaced font with no word-wrapping;
Some special notes when using this format:
- Text alignment should be done using spaces and not tabs;
- Because these notes are inside a DIV tag construct, markdown syntax cannot be used within it.

A more complex structure of information is also anticipated.

   @author Antonio Abreu
   @since 1.0

   Create the default set of custom tags.
   These tags are persisted as properties in a properties file and used with the comments processor.

   <div class="developerNote">
      <p>Notes:</p>
      <dl>
         <dt>Custom Tags</dt>
            <dd>Custom tags extend the set of tags provided by the
                <em>out-of-the-box</em> underlying library.
            </dd>
         <dt>Rationale</dt>
            <dd>This service was created to have some level of comments compatibility with
                the definitions commonly found in use at some customers.
            </dd>
            <dd>It is just to process the added tags, which kind of make sense, but with <strong>no</strong> default values.</dd>
      </dl>
   </div>

Other xHTML constructs may be attempted, but with no guaranteed results.
It is expected to have the rendering CSS be completely customizable in a future version of the tool.

Special Comment Processing

The _env field of Publishabe Documents

The _env field of Publishable Documents is a special document added by the webMethods platform for its own internal usage when publishing documents through the Broker. This structure is very extensive and potentially intrusive in the kind of documentation that is intended to be generated.

Services that define input/output arguments that are a reference to a Publishable Documents will have the comments of that document expanded as part of the service documentation. As a consequence, the _env structure is also referenced.

To avoid documenting a structure that does not relate directly with the service usage, the comment to a field named _env is assumed as:

         @conditional
         A field used and set by the system when the document is published.

Comments Guide

Introduction