Skip to main content

Lesson 8. Comments, annotations and descriptions

Example 8.1. User comments​

JSIGHT 0.3              
 
GET /cats/{id} // Get a cat by its id.
 
  ###
    This is block (multi-line)
    comment.
  ###
 
  200       # this is single-line comment
    {
      "id"  : 123,  // {min: 0}
      "name": "Tom"
    }

This example demonstrates both block and single-line comments (lines 5-8 and 10). Block comments are made with the character hash #, and multi-line comments with the triple hash ###.

Comments are ignored by parsers (this makes comments fundamentally different from annotations).

info

For more information about this topic, see:

Example 8.2. Annotations and directive "Description"​

JSIGHT 0.3              
 
GET /cats/{id} // Get a cat by its id.
 
  Description
    The request returns the data of the cat with
    the passed id, namely:
 
    - cat id,
    - cat name.
 
  200 // Successful response.
    {
      "id"  : 123,  // {min: 0} - Cat ID.
      "name": "Tom" //            Cat name.
    }

This example demonstrates the capabilities of the language in regard to the textual part of the API documentation, namely:

  • annotations;
  • directive Description.

Annotations look like comments in C-like programming languages. They enable you to add short textual descriptions to the internals of schemas (lines 14, 15) as well as to directives (lines 3, 12).

Annotations, unlike comments, are not ignored by the language parser, and are perceived as a full-fledged part of the API documentation.

The directive Description allows you to add lengthy text descriptions to other directives using markdown markup.

info

For more information about this topic, see: