[BioC] Bioconductor documentation

[Naomi Altman]

As always, I am grateful to the developers for donating their wonderful 
software.  However, the issue of why the documentation is hard to use keeps 
rearing its head, so ...

One of the problems I am finding with the Bioconductor documentation is 
that it is not sufficiently explicit, so I often need to go into the code 
to determine what the routine is doing.  As 2 examples,

lmFit (limma) can take as input an marrayNorm object and by default 
extracts "maM".  But if you type ?lmFit, this is not given in the 
documentation.  I have not looked at the Vignette to see if it is listed 
there.  However, I see the vignettes as tutorials - I should be able to 
find out what a routine does from its internal documentation.  The 
documentation should be explicit about what is extracted from each type of 
input object and what is output (if this differs by input object).  I might 
note that this is particularly cogent for limma, since limma works directly 
with contrasts for 2-color arrays, but requires an extra contrast step for 
1-channel arrays.

Similarly, I cannot tell from the documentation for maNorm or maNormMain 
whether the background values are used in the normalization.  I.e. the 
documentation should state which component of the input object will be used 
and how.

Thanks.

Naomi S. Altman                                814-865-3791 (voice)
Associate Professor
Bioinformatics Consulting Center
Dept. of Statistics                              814-863-7114 (fax)
Penn State University                         814-865-1348 (Statistics)
University Park, PA 16802-2111