Documentation for sandesh files

All messages generated by the controller and compute daemons are documented starting with 3.0 release. HTML documentation is automatically generated from the sandesh files and displayed as part of the contrail-analytics-api REST API for all the daemons - http://analytics-node-IP:8081/documentation/messages/index.html is the URL.

Let's consider the controller/src/io/io.sandesh file - https://github.com/Juniper/contrail-controller/blob/master/src/io/io.sandesh

For example, for sandesh systemlog message TcpServerMessageLog the documentation is added as:

/**
 * @description: System log for TCP server module
 * @severity: ERROR
 * @cause: An internal software failure occurred
 * @action: Contact your technical support representative
 */
systemlog sandesh TcpServerMessageLog {
    1: "Server";
    /** Name of server is usually the local endpoint */
    2: string ServerName;
    /** Direction is send '>' or receive '<' */
    3: string Direction;
    4: string Message;
}

Guidelines for adding documentation to the sandesh files

1. Any documentation is enclosed in /** */ comments.
2. Documentation about a sandesh message precedes the sandesh definition in the file and is indicated using /** */.
3. Developers can add general free-form documentation for a sandesh preceding the @ words.
4. @ words followed by space, tab, or ‘:’ will be added to a table in the documentation so that developers can add @action, @description, @severity, @cause fields. For object logs or UVEs, @object can be added to indicate the object the log is associated with. None of the @ words are mandatory, however guideline is to add @action, @cause for errors seen in field.
5. Documentation about fields precedes the field definition and is indicated using /**`` */
6. Documentation about structures precedes the structure definition and is indicated using /** */
7. Generic systemlog messages need to be changed to specific one so that appropriate descriptions can be added. Further, @severity fields are preferred to have only one value rather than using the same message for ERROR and DEBUG.
8. Sandesh file or module level documentation is added at the top of the file after the copyright.

Explanation of the generated HTML can be found at User Message Documentation