[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