[R] ?plot: Add an example on how to plot functions to the help of `plot`.

[Paul Menzel]

Am Donnerstag, den 28.07.2011, 09:12 +0200 schrieb Martin Maechler:
> >>>>> "PM" == Paul Menzel <paulepanter at users.sourceforge.net>
> >>>>>     on Wed, 27 Jul 2011 23:53:51 +0200 writes:

[…]

>     PM> So my newest suggestion is to add a comment to
> 
>     PM> plot(sin, -pi, 2*pi)
> 
>     PM> in `?plot`. Like
> 
>     PM> plot(sin, -pi, 2*pi) # Cf. ?plot.function
> 
>     PM> as `plot.function` is not explicitly mentioned in `?plot`.
> 
> Yes, I'll do that  {using 'see' instead of 'Cf.'}.

Thank you!

> Would it have helped you as beginner if instead of current
> 
> >  Generic X-Y Plotting
> > 
> >  Description:
> > 
> >       Generic function for plotting of R objects.  For more details
> >       about the graphical parameter arguments, see ‘par’.
> > 
> >  Usage:
> > 
> >       plot(x, y, ...)
> > 
> >  ....................
> >  ....................
> > 
> >  Details:
> > 
> >       For simple scatter plots, ‘plot.default’ will be used.  However,
> >       there are ‘plot’ methods for many R objects, including
> >       ‘function’s, ‘data.frame’s, ‘density’ objects, etc.  Use
> >       ‘methods(plot)’ and the documentation for these.
> > 
> >       The two step types differ in their x-y preference: Going from
> >       ........................
> 
> We would have moved the first paragraph from 'Details' to
> 'Description',  so that the help page would start with
> 
> >  Generic X-Y Plotting
> > 
> >  Description:
> > 
> >       Generic function for plotting of R objects.  For more details
> >       about the graphical parameter arguments, see ‘par’.
> > 
> >       For simple scatter plots, ‘plot.default’ will be used.  However,
> >       there are ‘plot’ methods for many R objects, including
> >       ‘function’s, ‘data.frame’s, ‘density’ objects, etc.  Use
> >       ‘methods(plot)’ and the documentation for these.
> > 
> >  Usage:
> > 
> >       plot(x, y, ...)
> > 
> >  ............
> 
> I.e.  would you have read the help page for plot.default 
> earlier, and realized that the ?plot page is by far not the only
> one to read,  if the paragraph above had come earlier ?

I am not sure if I would still have gone right to the examples. But
reading about `methods(plot)` earlier could have helped. In my opinion
your suggestion to move the paragraph up to the description is a good
thing. Still I would not have seen `plot.function` in the output of
`methods("plot")`.

        > methods("plot")
         [1] plot.acf*           plot.data.frame*    plot.decomposed.ts*
         [4] plot.default        plot.dendrogram*    plot.density       
         [7] plot.ecdf           plot.factor*        plot.formula*      
        [10] plot.hclust*        plot.histogram*     plot.HoltWinters*  
        [13] plot.isoreg*        plot.lm             plot.medpolish*    
        [16] plot.mlm            plot.ppr*           plot.prcomp*       
        [19] plot.princomp*      plot.profile.nls*   plot.spec          
        [22] plot.spec.coherency plot.spec.phase     plot.stepfun       
        [25] plot.stl*           plot.table*         plot.ts            
        [28] plot.tskernel*      plot.TukeyHSD      
        
           Non-visible functions are asterisked


Thanks,

Paul
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <https://stat.ethz.ch/pipermail/r-help/attachments/20110729/100f847c/attachment.bin>