commit d2e832d7b78b04dbd9c1d753f5db7d09ec2d7489 · pyrox.dev/nixpkgs

+28

doc/README.md

···

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

     

       214
        
       It also helps identifying long sentences at a glance.

     

       215
        
       

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       216
        
       ### Callouts and examples

     

       217
        
       

     

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

···

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

     

       214
        
       It also helps identifying long sentences at a glance.

     

       215
        
       

     

       216
       +
       ### Writing Function Documentation

     

       217
       +
       

     

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

     

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

     

       220
       +
       

     

       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
       +
       the first sentence is in present tense, active voice, and the subject is omitted, referring implicitly to the name of the function.

     

       223
       +
       For example:

     

       224
       +
       

     

       225
       +
       ```nix

     

       226
       +
       /**

     

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

     

       228
       +
       

     

       229
       +
         Returns the difference as a number.

     

       230
       +
       */

     

       231
       +
       subtractValues # ...elided code

     

       232
       +
       ```

     

       233
       +
       

     

       234
       +
       Renders as:

     

       235
       +
       

     

       236
       +
       ```md

     

       237
       +
       ## `subtractValues`

     

       238
       +
       

     

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

     

       240
       +
       

     

       241
       +
       Returns the difference as a number.

     

       242
       +
       ```

     

       243
       +
       

     

       244
        
       ### Callouts and examples

     

       245
        
       

     

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