[R6RS] document style
    Matthew Flatt 
    mflatt at cs.utah.edu
       
    Tue Aug 29 19:21:31 EDT 2006
    
    
  
For documenting procedures (and some forms), I think the right style is
 (foo arg ...)      procedure
 
 Returns ....
That is, the first sentence has an implicit subject (from the prototype
above), and so it starts with a verb.
In the case that the domain needs to be specified more completely, I
think the right style is
 (foo arg ...)      procedure
 
 `arg' must be ... The `foo' procedure returns ....
That is, after the domain is clarified, the explanation starts again
with "The <name> procedure".
A lot of the current draft says "this procedure" in both of the above
cases, and I think we want to replace those uses.
Does that sound right?
(I imagine that we don't need to fix this level of detail by Friday or
even Tuesday. But as I make changes, I'd like to get them right.)
Thanks,
Matthew
    
    
More information about the R6RS
mailing list