Changes between Version 47 and Version 48 of Commentary/CodingStyle


Ignore:
Timestamp:
Jul 14, 2014 2:39:53 PM (8 months ago)
Author:
tibbe
Comment:

Add a section on top-level Haddock docs

Legend:

Unmodified
Added
Removed
Modified
  • Commentary/CodingStyle

    v47 v48  
    1414 
    1515== Comments == 
     16 
     17There are two kinds of comments in source code, comments that describe the interface (i.e. how is this supposed to be used) and comments that describe the implementation (e.g. subtle gotchas). 
     18 
     19=== Comments on top-level entities === 
     20 
     21Every top-level entity should have a Haddock comment that describes what it does and, if needed, why it's there. Example: 
     22 
     23{{{ 
     24-- | Returns which registers are read and written by this  
     25-- instruction, as a (read, written) pair. This info is used 
     26-- by the register allocator. 
     27x86_regUsageOfInstr :: Platform -> Instr -> RegUsage 
     28}}} 
     29 
     30We use Haddock so that the comment is included in the generated HTML documentation. 
    1631 
    1732=== Comments and commit messages ===