# SCM Repository

[inlinedocs] View of /pkg/inlinedocs/man/extract.docs.setClass.Rd
 [inlinedocs] / pkg / inlinedocs / man / extract.docs.setClass.Rd

# View of /pkg/inlinedocs/man/extract.docs.setClass.Rd

Revision 396 - (download) (as text) (annotate)
Tue Feb 18 13:07:32 2014 UTC (5 years, 7 months ago) by markus
File size: 1712 byte(s)
This is the next intermediate commit.
Its main purpose is to make the package pass the cran checks so that further collaboration is not hindered.
Many of the functions I introduced and documented sparsely are not too probable to survive in their current
form.
The reason is the following:
Regarding design this version is in the middle of the path from the aspect oriented version I started with to the hierarchical version I have in mind and could maintain much easier.
E.g. I got rid of package.skeleton and inlinedocs now writes (most of ) the rd files.
This is not true for lists and similar stuff yet.
My final goal would be to get also rid of modify.Rd.file and move its functionality to the functions that now replace
package.skeleton.
If that is achieved we would be left with only two steps ( or "aspects").
1.) gather the information from the source into an environment
2.) pass the whole environment to the various Rd file writers that write the completed files instead of parsing the templates

The last step
3.) (filling the *.Rd files with  content)

would not be necessary any longer.

I also hope to simplify the first step considerably.
1.1)
When I started the most abstract thing we had to deal with was the list of objects.
This however does not contain generics, methods or classes.
To extract those you need the whole (populated) environment.
So step 1) will in future just populate an environment and leave the details to specialized functions.
E.g. the (present) object list would then only be created by the function that writes Rd files for functions.
The function that document Methods dont need it.
At the moment the interfaces are in the process of change so that objects, the  environment , Methodlists, lists of Generics  are passed around for everyone to pick what he needs. This intermediate mess is not there to stay.

1.2)
A second thing that caused a lot of work, was the parsing of the code files to produce the doc links.
I introduced a good deal of duplication here, that is however also not there to stay but a step towards reducing this kind of thing altogether but in tiny steps (seperately for classes methods and so on)
I would very much like to avoid parsing a setMethod (or setClass) statement altogether.
Presently this is necessary to find out the signature of the mehtod in question only to store the doc link relevant info  with the right key to rejoin it later with the other docs for that method.
The effort to do so is enormous. E.g. I have to reassemble the argument list of a setMethod( )call to be sure what is what in the following text. The sad thing is that the R parser does this (effortlessly) anyway when the environment is populated.
Therefore I propose to research the  srcref features in R, that would help us to find the src chunk of a method by asking the
method object in the environment where it came from and find the preceding comments this way.

This is what I am driving towards.
So the apparent inconsistency is a reflection of ongoing design change.

To faciliate this migration I have also included some more unit tests (27 runit tests now) and some small helper scripts to run them continiously and in parallel whenever the tiniest bit of code in inlinedocs/R is touched.
You find them in

...testfiles/mm.

The tests duplicate a lot of code (thereby  asking  for a setup mehtod.)
To use them as extended documentation I however prioritised readability and therefor made every test independent to understand.

D    pkg/inlinedocs/inst/scratch/inlinedocsTest
D    pkg/inlinedocs/inst/scratch/tw_testIndent.R
D    pkg/inlinedocs/inst/etc/default-function.R
D    pkg/inlinedocs/inst/etc/users.org
D    pkg/inlinedocs/inst/etc/anne-parse.R
D    pkg/inlinedocs/inst/etc/make.R
D    pkg/inlinedocs/inst/etc/tags
D    pkg/inlinedocs/inst/etc/inner.function
D    pkg/inlinedocs/inst/etc/parseRd.R
D    pkg/inlinedocs/inst/etc/anne.R
D    pkg/inlinedocs/inst/etc/minimalErrorPkg
D    pkg/inlinedocs/inst/etc/author.from.author.R
AM   pkg/inlinedocs/inst/testfiles/csall.sh
M    pkg/inlinedocs/inst/testfiles/mm/runit.NamespaceExample.R
A    pkg/inlinedocs/inst/testfiles/mm/srcref.example.R
D    pkg/inlinedocs/inst/testfiles/mm/package.skeleton.R
AM   pkg/inlinedocs/inst/testfiles/mm/cisall.sh
M    pkg/inlinedocs/inst/testfiles/mm/runit.Infrastructure.R
D    pkg/inlinedocs/inst/testfiles/mm/runit.OperatorDoc.R
AM   pkg/inlinedocs/inst/testfiles/mm/continousRunner.sh
A    pkg/inlinedocs/inst/testfiles/mm/help.R
M    pkg/inlinedocs/inst/testfiles/mm/Itest.R
A    pkg/inlinedocs/inst/testfiles/mm/findGenericsAndMethodsWithSrcrefs.R
A    pkg/inlinedocs/inst/testfiles/mm/runit.ClassDoc.R
A    pkg/inlinedocs/inst/testfiles/mm/runit.MethodExample.R
M    pkg/inlinedocs/inst/testfiles/mm/isolatedTestRunner.R
A    pkg/inlinedocs/inst/testfiles/mm/runit.FunctionExample.R
M    pkg/inlinedocs/inst/testfiles/mm/isall.R
AM   pkg/inlinedocs/inst/testfiles/mm/cITest.sh
M    pkg/inlinedocs/inst/testfiles/mm/runit.MethodDoc.R
A    pkg/inlinedocs/inst/testfiles/mm/runit.RepairUsage.R
A    pkg/inlinedocs/inst/testfiles/lastrun
M    pkg/inlinedocs/R/package.skeleton.dx.R
M    pkg/inlinedocs/R/test.R
M    pkg/inlinedocs/R/parsers.R
M    pkg/inlinedocs/R/utils.R
M    pkg/inlinedocs/R/testhelpers.R
M    pkg/inlinedocs/DESCRIPTION
A    pkg/inlinedocs/man/writeMethodRdFiles.Rd
A    pkg/inlinedocs/man/MethodsWithSrcRefForGen.Rd
M    pkg/inlinedocs/man/removeAliasesfrom.Rd.file.Rd
A    pkg/inlinedocs/man/methSrc.Rd
A    pkg/inlinedocs/man/mm.examples.from.testfile.Rd
M    pkg/inlinedocs/man/modify.Rd.file.Rd
A    pkg/inlinedocs/man/sigString.Rd
A    pkg/inlinedocs/man/writeFunctionRdFiles.Rd
A    pkg/inlinedocs/man/removeComma.Rd
A    pkg/inlinedocs/man/rewriteSetMethodArgs.Rd
M    pkg/inlinedocs/man/print.allfun.Rd
A    pkg/inlinedocs/man/extra.class.docs.Rd
A    pkg/inlinedocs/man/pp.Rd
M    pkg/inlinedocs/man/package.skeleton.dx.Rd
A    pkg/inlinedocs/man/definition.from.source.Rd
A    pkg/inlinedocs/man/writePackageRdFile.Rd
A    pkg/inlinedocs/man/extract.docs.Rd
M    pkg/inlinedocs/man/apply.parsers.Rd
A    pkg/inlinedocs/man/z[-methods.Rd
M    pkg/inlinedocs/man/combine.character.Rd
A    pkg/inlinedocs/man/hiddenClasses.Rd
M    pkg/inlinedocs/man/combine.Rd
A    pkg/inlinedocs/man/writeMethodTableRdFiles.Rd
M    pkg/inlinedocs/man/findGeneric.Rd
M    pkg/inlinedocs/man/inlinedocs-package.Rd
A    pkg/inlinedocs/man/getMethodName.Rd
M    pkg/inlinedocs/man/extract.docs.setClass.Rd
A    pkg/inlinedocs/man/exportedFunctions.Rd
M    pkg/inlinedocs/man/extra.code.docs.Rd
M    pkg/inlinedocs/man/make.package.and.check.Rd
A    pkg/inlinedocs/man/allClasses.Rd
M    pkg/inlinedocs/man/save.test.result.Rd
A    pkg/inlinedocs/man/writeClassRdFiles.Rd
A    pkg/inlinedocs/man/exported.Rd
M    pkg/inlinedocs/man/get_S3_primitive_generics.Rd
M    pkg/inlinedocs/man/test.file.Rd
M    pkg/inlinedocs/man/extract.file.parse.Rd
A    pkg/inlinedocs/man/z[_method__listOfMethods_logical.Rd
A    pkg/inlinedocs/man/methodDocName.Rd
A    pkg/inlinedocs/man/exportedClasses.Rd
M    pkg/inlinedocs/man/extract.docs.file.Rd
A    pkg/inlinedocs/man/GenHasAnyMethodWithSrc.Rd
M    pkg/inlinedocs/man/getKnownS3generics.Rd
M    pkg/inlinedocs/man/is_primitive_in_base.Rd
A    pkg/inlinedocs/man/MethodHasSrc.Rd
M    pkg/inlinedocs/man/fixPackageFileNames.Rd
A    pkg/inlinedocs/man/trimmedNonEmptyLines.Rd
A    pkg/inlinedocs/man/getMethodSrc.Rd
A    pkg/inlinedocs/man/methodTable.Rd
A    pkg/inlinedocs/man/MethodSignatureHasOnlyExportedClasses.Rd
M    pkg/inlinedocs/man/replace.one.Rd
A    pkg/inlinedocs/man/CompareTrimmedNonEmptyLines.Rd
M    pkg/inlinedocs/man/get_internal_S3_generics.Rd
M    pkg/inlinedocs/man/forfun.Rd
A    pkg/inlinedocs/man/mmPromptMethods.Rd
M    pkg/inlinedocs/man/getSource.Rd
A    pkg/inlinedocs/man/documentableMeths.Rd
A    pkg/inlinedocs/man/pe.Rd
A    pkg/inlinedocs/man/GenHasAnyExposedMethod.Rd
A    pkg/inlinedocs/man/exportedGenerics.Rd
M    pkg/inlinedocs/man/decomment.Rd
A    pkg/inlinedocs/man/createObjects.Rd
A    pkg/inlinedocs/man/GenHasSrc.Rd
A    pkg/inlinedocs/man/exportedDocumentableMeths.Rd
M    pkg/inlinedocs/man/prefixed.lines.Rd
M    pkg/inlinedocs/man/forall.Rd
A    pkg/inlinedocs/man/title.from.firstline.Rd
M    pkg/inlinedocs/man/kill.prefix.whitespace.Rd
M    pkg/inlinedocs/man/combine.NULL.Rd
M    pkg/inlinedocs/man/combine.list.Rd
A    pkg/inlinedocs/man/extra.method.docs.Rd
A    pkg/inlinedocs/man/inherit.docs.Rd
M    pkg/inlinedocs/man/extract.xxx.chunks.Rd
M    pkg/inlinedocs/man/do.not.generate.Rd
A    pkg/inlinedocs/man/extract.docs.setMethod.Rd
A    pkg/inlinedocs/man/methSig.Rd
A    pkg/inlinedocs/man/manMan
A    pkg/inlinedocs/man/manMan/descfile.names.Rd
A    pkg/inlinedocs/man/manMan/default.parsers.Rd
A    pkg/inlinedocs/man/manMan/lonely.Rd
A    pkg/inlinedocs/man/manMan/nondesc.parsers.Rd
A    pkg/inlinedocs/man/manMan/non.descfile.names.Rd
A    pkg/inlinedocs/man/manMan/forall.parsers.Rd
A    pkg/inlinedocs/man/manMan/forfun.parsers.Rd
A    pkg/inlinedocs/man/manMan/prefix.Rd
M    pkg/inlinedocs/NAMESPACE
M    pkg/inlinedocs/NEWS

\name{extract.docs.setClass}
\alias{extract.docs.setClass}
\title{S4 class inline documentation}
\description{Using the same conventions as for functions, definitions of S4 classes
in the form \code{setClass("classname",\dots)} are also located and
scanned for inline comments.}
Note that \code{source} statements are \emph{ignored} when scanning for
class definitions.}
}
\details{Extraction of S4 class documentation is currently limited to expressions
within the source code which have first line starting with
\code{setClass("classname"}. These are located from the source file
(allowing also for white space around the \code{setClass} and \code{(}).
Note that \code{"classname"} must be a quoted character string;
expressions returning such a string are not matched.

For class definitions, the slots (elements of the
\code{representation} list) fill the role of function
arguments, so may be documented by \code{##<<} comments on
the same line or \code{### } comments at the beginning of the
following line.

If there is no explicit title on the first line of setClass, then
one is made up from the class name.

The class definition skeleton includes an \code{Objects from the Class}
section, to which any \code{##details<<} documentation chunks are
written. It is given a vanilla content if there are no specific
\code{##details<<} documentation chunks.}

\author{Toby Dylan Hocking <toby@sg.cs.titech.ac.jp> [aut, cre], Keith Ponting [aut], Thomas Wutzler [aut], Philippe Grosjean [aut], Markus Müller [aut], R Core Team [ctb, cph]}



 root@r-forge.r-project.org ViewVC Help Powered by ViewVC 1.0.0
Thanks to: