On this page:

Generating Slice Documentation

If you look at the online Slice API reference, you will find reference documentation for all the Slice definitions used by Ice and its services. In the binary distributions of Ice, you will also find HTML documentation that contains the same information. The HTML documentation is generated from special comments in the Slice definitions using slice2html, a tool that scans Slice definitions for special comments and generates HTML pages for those comments.

As an example of documentation comments, here is the definition of Ice::Current:

{zcode:slice}
/**
 *
 * Information about the current method invocation for servers.
 * Each operation on the server has a [Current] as its implicit
 * final parameter. [Current] is mostly used for Ice services.
 * Most applications ignore this parameter.
 *
 **/
local struct Current {
    /**
     * The object adapter.
     **/
    ObjectAdapter adapter;
    
    /**
     * Information about the connection over which the current
     * method invocation was received. If the invocation is direct
     * due to collocation optimization, this value is set to null.
     **/
    Connection con;

    /**
     * The Ice object identity.
     **/
    Identity id;

    /**
     * The facet.
     ***/
    string facet;

    /**
     * The operation name.
     **/
    string operation;

    /**
     * The mode of the operation.
     **/
    OperationMode mode;

    /**
     * The request context, as received from the client.
     **/
    Context ctx;

    /**
     * The request id unless oneway (0) or collocated (-1).
     **/
    int requestId;
};
{zcode}

If you look at the comments, you will see these reflected in the documentation for Ice::Current in the online Slice API Reference.

Documentation Comments

A documentation comment:

Such a comment can precede any Slice construct, such as a module, interface, structure, operation, and so on. Within a documentation comment, you can either start each line with a *, or you can leave the beginning of the line blank — slice2html can handle either convention:

{zcode:slice}
/**
 *
 * This is a documentation comment for which every line
 * starts with a '*' character.
 **/

/**

 This is a documentation comment without a leading '*'
 for each line. Either style of comment is fine.

 **/
{zcode}

The first sentence of the documentation comment for a Slice construct should be a summary sentence. slice2html generates an index of all Slice constructs; the first sentence of the comments for each Slice construct is ued as a summary in that index.

Hyperlinks

Any Slice identifier enclosed in square brackets is presented as a hyperlink in code font. For example:

{zcode:slice}
/**
 * An empty [name] denotes a null object.
 **/
{zcode}

This generates a hyperlink for the name markup that points at the definition of the corresponding Slice symbol. (The symbol can denote any Slice construct, such as a type, interface, parameter, or structure member.)

Explicit Cross-References

The directive @see is recognized by slice2html. Where it appears, the generated HTML contains a separate section titled "See Also", followed by a list of Slice identifiers. For example:

{zcode:slice}
/**
 * The object adapter, which is responsible for receiving requests
 * from endpoints, and for mapping between servants, identities,
 * and proxies.
 *
 * @see Communicator
 * @see ServantLocator
 **/
{zcode}

The Slice identifiers are listed in the corresponding "See Also" section as hyperlinks in code font.

Markup for Operations

There are three directives specifically to document Slice operations: @param, @return, and @throws. For example:

{zcode:slice}
/**
 * Look for an item with the specified
 * primary and secondary key.
 *
 * @param p The primary search key.
 *
 * @param s The secondary search key.
 *
 * @return The item that matches the specified keys.
 *
 * @throws NotFound Raised if no item matches the specified keys.
 **/

Item findItem(Key p, Key s) throws NotFound;
{zcode}

slice2html generates separate "Parameters", "Return Value", and "Exceptions" sections for these directives. Parameters are listed in the same order as they appear in the comments. (For clarity, that order should match the order of declaration of parameters for the corresponding operation.)

General HTML Markup

A documentation comment can contain any markup that is permitted by HTML in that place. For example, you can create separate paragraphs with <P> and </P> elements:

{zcode:slice}
/**
 * This is a comment for some Slice construct.</p>
 *
 * <p>This comment appears in a separate paragraph.
 **/
{zcode}

Note that you must neither begin a documentation comment with a <p> element nor end it with a </p> element because, in the generated HTML, documentation comments are already surrounded by <p> and </p> elements.

There are various other ways to create markup — for example, you can use <table> or <ul> elements. Please see the HTML specification for details.

Using slice2html

slice2html uses the following syntax:

{zcode}
slice2html [options] slice_file...
{zcode}

If you have cross-references that span Slice files, you must compile all of the Slice files with a single invocation of slice2html.

The command supports the following options:

See Also