commit d2e832d7b78b04dbd9c1d753f5db7d09ec2d7489 · pyrox.dev/nixpkgs

+28
doc/README.md
···

       213
       213
        
       This makes reviews and suggestions much easier, since GitHub's review system is based on lines.

     

       214
       214
        
       It also helps identifying long sentences at a glance.

     

       215
       215
        
       

     

       216
       216
       +
       ### Writing Function Documentation

     

       217
       217
       +
       

     

       218
       218
       +
       Function documentation is *reference documentation*, for which

     

       219
       219
       +
       [diataxis Reference documentation](https://diataxis.fr/reference/) (8 minutes) is **mandatory reading**.

     

       220
       220
       +
       

     

       221
       221
       +
       On top of the diataxis framework, which provides a balanced perspective on what reference documentation should contain, we apply a specific style rule to function documentation:

     

       222
       222
       +
       the first sentence is in present tense, active voice, and the subject is omitted, referring implicitly to the name of the function.

     

       223
       223
       +
       For example:

     

       224
       224
       +
       

     

       225
       225
       +
       ```nix

     

       226
       226
       +
       /**

     

       227
       227
       +
         Subtracts value `b` from value `a`.

     

       228
       228
       +
       

     

       229
       229
       +
         Returns the difference as a number.

     

       230
       230
       +
       */

     

       231
       231
       +
       subtractValues # ...elided code

     

       232
       232
       +
       ```

     

       233
       233
       +
       

     

       234
       234
       +
       Renders as:

     

       235
       235
       +
       

     

       236
       236
       +
       ```md

     

       237
       237
       +
       ## `subtractValues`

     

       238
       238
       +
       

     

       239
       239
       +
       Subtracts value `b` from value `a`.

     

       240
       240
       +
       

     

       241
       241
       +
       Returns the difference as a number.

     

       242
       242
       +
       ```

     

       243
       243
       +
       

     

       216
       244
        
       ### Callouts and examples

     

       217
       245
        
       

     

       218
       246
        
       Use the [admonition syntax](#admonitions) for callouts and examples.