Document Vrouter Sandesh messages

[Hari Prasad Killi]

Hello Contrail Software Developers,
As part of 3.0 release, we are required to document all messages generated by the controller and compute daemons. The analytics team has added code to mainline to automatically generate HTML documentation from the sandesh files and display it as part of the contrail-analytics-api REST API for all the daemons - http://<controller-IP>:8081/documentation/messages is the URL.

All contrail software developers will need to add appropriate documentation to the sandesh files so that all the generated messages are documented properly. As example, I have added documentation to controller/src/io/io.sandesh file - https://github.com/Juniper/contrail-controller/blob/master/src/io/io.sandesh

For example, for sandesh system log message TcpServerMessageLog:

/**

* @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;

}

The 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. Developers will need to change generic systemlog messages 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. For example, for io.sandesh, following is the module level documentation:

/**

* Message definitions for IO and EventManager modules.

*

* The EventManager module is responsible for handling IO and timer events

* in a daemon.

*

* The IO module is responsible for handling TCP and UDP IO server and client

* in a daemon.

*/

You can also find the guidelines at https://github.com/Juniper/contrail-controller/wiki/Documentation-for-sandesh-files

Thanks and please let me know any concerns/questions.

Megh

[OpenContrail Admin (ci-admin-f)]

Review in progress for https://review.opencontrail.org/16583
Submitter: Kumar Harsh (<email address hidden>)

[OpenContrail Admin (ci-admin-f)]

Reviewed: https://review.opencontrail.org/16583
Committed: http://github.org/Juniper/contrail-controller/commit/ae74481b039f5a20dbc30629174dc1bbebad7cdb
Submitter: Zuul
Branch: master

commit ae74481b039f5a20dbc30629174dc1bbebad7cdb
Author: harsh <email address hidden>
Date: Tue Feb 2 12:21:36 2016 +0530

Document Vrouter Sandesh messages

Conflicts:

 src/vnsw/agent/controller/controller.sandesh

Change-Id: Id7a86c8102265e975a8e811adc7a940cfd9c9d9c
Closes-Bug: #1531822