code.vegaprotocol.io/vega@v0.79.0/DOCUMENTATION_STYLE.md (about)

     1  # API docs style guide
     2  
     3  When writing docs annotations for the protos, refer to the following guidance for good practices and specific style choices. While some of the guidance below is specific to protos, the general good practice tips are applicable to all docs.
     4  
     5  ## Good practice tips
     6  
     7  - Look at how other doc-strings are written and formatted as a guide
     8  - Check your spelling for typos
     9  - Make sure you didn’t just copy and paste from a different string
    10  - Imagine trying to interact with the API as an end user, and write with that in mind
    11  
    12  ## Title structure
    13  
    14  Text should match the rpc endpoints and have the titles like:
    15  - “List Deposits” instead of “Deposits list”
    16  - “Get Deposit” instead of “Deposit”
    17  
    18  When adding a new API, if the title seems a bit odd, reconsider the rpc endpoint name. “Get governances” for example, is not a real word and isn’t a helpful title.
    19  
    20  ## Naming terminology
    21  
    22  - **Get**: Used when API is for requesting a single data point. Get order; Get latest trade.
    23  - **List**: Used when API is for requesting multiple data points. List orders; List trades; List network parameters.
    24  - **Estimate**: Used when API is requesting approximate information based on other pieces of data. Estimate margin; Estimate fee.
    25  - **Export**: Used when API will provide a CSV file output of the data, or potentially other output formats.
    26  - **Observe**: Used for WebSocket only, to denote streaming/subscription. Observe trades; Observe candle data.
    27  
    28  If your new API doesn't fit into any of these categories then this is a prompt to start a discussion about the best name for it.
    29  
    30  ## What not to use, and what to use instead
    31  
    32  - I
    33  - You
    34  - We
    35  - Id, id, or identifier
    36    - *USE*: ID
    37  - ID of X
    38    - *USE*: X ID. Example: Market ID, *not* ID of the market
    39  - data-node, or datanode
    40    - *USE*: data node
    41  - Pubkey
    42    - *USE*: party ID, optionally can describe that party ID is the same as public key
    43  
    44  ## Wording
    45  
    46  - Use the imperative verb. Example: “Get a list”, *not* “Gets a list”
    47  - Use standardised information for pagination connection.
    48    - Example: “Page of positions data and corresponding page information.”, *not* “List of 0 or more positions.”
    49  - The description should not be the title repeated.
    50    - Example: “Get deposit”, should say more than just “Get deposit.” as a summary.
    51  
    52  ## Things to avoid
    53  
    54  - Statements in parentheses
    55    - Example: ”Get the current network limits, such as if bootstrapping is finished, and if proposals are enabled, etc.”, *not* “Get the current network limits (is bootstrapping finished, are proposals enabled etc..)”
    56  - Beginning descriptions with A/an/the
    57    - Example: “Name of the node operator”, *not* “The name of the node operator”
    58  
    59  ## Capitalisation
    60  
    61  - Capitalise Vega. If referring to the token, use VEGA
    62  - REST, GraphQL, gRPC, Tendermint (or CometBFT), ERC-20, etc.
    63  - CSV
    64  - ERC-20. In some cases it’s already coded as ERC20 so that is an exception, but it should be capitalised, at a minimum
    65  - Unless it’s a specific project name, transport, or registered name, it does not need to be capitalised
    66  - *Do not capitalise* protocol upgrade, trade, data node, validator, node operator, core, etc..
    67  
    68  ## Add helpful guidance for users
    69  
    70  - If a returned value is a string that represents an integer, ensure that it describes if it is a signed or unsigned integer. Note: If the field is described as a number but the data type is a string, it is so that there is no loss of precision, or risk of integer overflow for large numbers.
    71  - If it’s a string that represents a decimalised number, describe how someone can determine what the decimal place is.
    72  
    73  ## Formatting protos
    74  
    75  Use correct formatting when adding new API endpoints to the protos:
    76  
    77  - Required fields
    78  - Tags - Choose from existing tags before adding a new tag. Tags are used to group similar APIs together in the REST documentation. If your new API doesn't fit into any of the existing tags, then this is a prompt to start a discussion about the best category for it.
    79  - Titles & descriptions
    80  - Use a full stop for a description with no title.
    81  
    82  ### How to format a proto API
    83  
    84  ```
    85  service ColourService {
    86    // Get colour
    87    //
    88    // Get the first colour that this API offers
    89    rpc GetColour(GetColourRequest) returns (GetColourResponse) {}
    90    // List colours
    91    //
    92    // List all the colours available
    93    rpc ListColours(ListColoursRequest) returns (ListColoursResponse) {}
    94  }
    95  
    96  // Request for more information about colours.
    97  //
    98  // The response with details for each colour.
    99  message ListColoursRequest {
   100     // Determines if colours that use blue should be shown.
   101     bool with_blue = 1;
   102  
   103     // There are lots of colours, so you can paginate the results.
   104     optional Pagination pagination = 2;
   105  }
   106  ```
   107  
   108  ### Generic format for title and description
   109  
   110  ```
   111  #### example
   112  
   113  // This is a title, which needs to have a blank line below it
   114  //
   115  // This is a description
   116  // You can add more descriptions on further lines
   117  string my_field = 1;
   118  
   119  #### next example
   120  
   121  // This is a title, and has no full stop at the end
   122  
   123  #### next example
   124  
   125  // This is a description, and it needs a full stop at the end.
   126  string my_field =1;
   127  ```
   128  
   129  ### Required and optional fields
   130  All fields in an API request should either be required and marked with “[(google.api.field.behaviour = REQUIRED)]”, or optional and marked explicitly as “optional” against the type in the protos.
   131  
   132  When describing a field in a doc-string, it does not need to explicitly say whether it is optional or required. It is implied by the annotations.
   133  
   134  Example: *Do not* start a doc-string with “Optionally….”, or end one with “is required.”
   135  
   136  *If a field is optional* describe what happens if it is not set, but only if it is not obvious.
   137  
   138  Example: An optional field that filters the returned list. It can be made clear in the description (words like “restrict” and “filter”) that not providing a value will return them all. On the other hand, an optional field that takes an epoch-seq will need to state somewhere that not setting it will return the data for latest epoch.
   139  
   140  *Do not* use fields that do not use “optional” but where the default value means “not set/ignored”, for example:
   141  
   142  ```
   143  message NewAPIRequest {
   144  
   145      // A required field. Being set to “” is a VALIDATION ERROR
   146      string market_id = 1; [(google.api.field.behaviour = REQUIRED)]
   147  
   148      // An optional field.
   149      optional string party_id = 2;
   150  
   151      // DO NOT DO THIS
   152      // Optional asset_id, if empty will not filter on asset_id
   153      string asset_id = 3;
   154  
   155  }
   156  
   157  ```