[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