Bug 17279 - parameter "amount" is badly explained for jitter()
Summary: parameter "amount" is badly explained for jitter()
Status: UNCONFIRMED
Alias: None
Product: R
Classification: Unclassified
Component: Documentation (show other bugs)
Version: R 3.3.*
Hardware: All All
: P5 enhancement
Assignee: R-core
URL:
Depends on:
Blocks:
 
Reported: 2017-05-26 08:43 UTC by Ulrich Windl
Modified: 2017-05-26 08:43 UTC (History)
0 users

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Ulrich Windl 2017-05-26 08:43:43 UTC
In the manual page for jitter(), the description of parameter "amount" makes a forward reference to a parameter "z" that is explained later ("if ‘= 0’ the default is ‘factor * z/50’").

In general, avoid forward references in manual pages; if unavoidable, mention 
where the reference will be explained.

In the "Description" section the parameter "z" is explained, and another parameter "d" is introduced that only used for parameter "amount".

In general if a variable is "local" to some parameter, explain that variable there. ("we set ‘a <- factor * d/5’ where _d_ is the smallest difference between adjacent unique (apart from fuzz) ‘x’ values.")

Therefore I suggest to move descriptions of "z" and "d" into the description of parameter "amount". The positive side-effect will be that the description of jitter() becomes very short (and "crispy").

In general putting the description in front of the parameters also seems like a good idea to me, because why should you read a long description of parameters when you want to find out what a function does (maybe that is not the function you are looking for)?

It may not be an argument, but in UNIX manual pages "OPTIONS" always follow "DESCRIPTION", probably for a good reason.