# SCM Repository

[inlinedocs] View of /pkg/inlinedocs/man/extract.file.parse.Rd
 [inlinedocs] / pkg / inlinedocs / man / extract.file.parse.Rd

# View of /pkg/inlinedocs/man/extract.file.parse.Rd

Tue Feb 18 13:07:32 2014 UTC (5 years, 6 months ago) by markus
File size: 2321 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.file.parse}
\alias{extract.file.parse}
\title{File content analysis}
\description{Using the base \code{parse} function, analyse the file to link
the default description for that chunk. The analysis also looks for
S4 class "setClass" ,R.oo setConstructorS3  R.methodsS3::setMethodS3
or S4 setMethod calls in order to link the documentation of those properly.}
\usage{extract.file.parse(code, env)}\arguments{
\item{code}{Lines of R source code in a character vector - note that any
nested \code{source} statements are \emph{ignored} when scanning
for class definitions.}
\item{env}{the environment in which the code has been evaluated before.
This is e.g. iportant to make sure that we can evaluate expressions
like signature definitions for methods }
}
\details{If the definition chunk does not contain a
description, any immediately preceding sequence consecutive
"prefix" lines will be used instead.

Class and method definitions can take several forms,
determined by expression type: \describe{
\item{assignment (<-)}{Ordinary assignment of value/function;}
\item{setClass}{Definition of S4 class;}
\item{setMethod}{Definition of a method of a S4 generic;}
\item{setConstructorS3}{Definition of S3 class using R.oo package;}
\item{R.methodsS3::setMethodS3}{Definition of method for S3 class using R.oo package.}}
Additionally, the value may be a name of a function defined elsewhere,
in which case the documentation should be copied from that other definition.
This is handled using the concept of documentation links.

complexity: they will define an additional S3 generic (which
needs documentation to avoid warnings at package build time)
documentation. A previously unseen S3generic is linked to the
first defining instances, subsequent definitions of that S3generic
also link back to the first defining instance.}
\value{Returns an invisible list of .DocLink objects.}

\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]}