SCM

SCM Repository

[inlinedocs] View of /pkg/inlinedocs/NEWS
ViewVC logotype

View of /pkg/inlinedocs/NEWS

Parent Directory Parent Directory | Revision Log Revision Log


Revision 396 - (download) (annotate)
Tue Feb 18 13:07:32 2014 UTC (5 years, 3 months ago) by markus
File size: 8581 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
M    pkg/inlinedocs/inst/testfiles/mm/runit.AddExampleCodeFromExternalTest.R
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
M    pkg/inlinedocs/man/leadingS3generic.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
== TODO

As of R 3.0, the "parser now incorporates code from Romain Francois'
parser package, to support more detailed computation on the code, such
as syntax highlighting, comment-based documentation, etc. Functions
getParseData() and getParseText() access the data." We should exploit
this in inlinedocs Parser Functions.

Attempt doc list to Rd list conversion, so we can generate Rd using
tools:::print.Rd. See code in etc/parseRd.R

Try to get more tests working: R CMD check and Rd conversion to
doclist checks.

Rd generation for attrSetter<- functions?

Functions with {} as default arguments => error. See
etc/default-function.R

2013.9.3 copy utils code to utils.R so we do not have to use utils:::
and so we can now pass R CMD check for R-devel on CRAN.

Authors@R support.

2013.8.22 citation for JSS paper.

2013.7.23 citation bugfix and if(interactive()) in
package.skeleton.dx() examples to reduce check time.

== 1.9.3 --- 6 March 2013

Rd generation for "[.class" as in quadmod... this currently works but
since when?

== 1.9.2 --- 28 Jan 2013

Pierre Neuvial reports that concatenating files with comments at the
last line sometimes results in unexpected documentation associated
with the first object defined in the next file. Thus now we issue a
warning whenever there is a comment on the last line of an .R file.

check for existence of files in removeAliasesfrom.Rd.file, since they
sometimes will not exist due to do.not.generate.

== 1.9.1 --- 21 May 2012

use --as-cran for tests!

R CMD check --as-cran inlinedocs_1.9.tar.gz had 
* checking Rd cross-references ... WARNING
... this seems to be related to \link{} tags in Rd?
... or some strange bug in R CMD check?
https://bugs.r-project.org/bugzilla3/show_bug.cgi?id=14875

pause for 4 seconds in example for do.not.generate. On windows the
filesystem records mtimes with a resolution of 2 seconds, so if we
want to see that a file has changed we need to wait at least this
long.

== 1.9 --- 13 Jan 2012 -> 5 April 2012

move code for generating a DESCRIPTION file into package.skeleton.dx.

doc bugfix for some \code{} chunks in inlinedocs that were
disappearing.

Added inst/silly/NAMESPACE to avoid warnings on package check, and
copy this over to all the mini test packages that are created for each
of the inst/testfiles.

Use \s space instead of \W in regexp for "delete empty sections to
suppress warnings in R CMD check." This was causing a bug for
i.e. \code{+} and \code{%*%} in the doc for the FUN argument of the
apply function.

do.not.generate("rd1","rd2") returns a Parser Function which will
cause rd1.Rd and rd2.Rd to not be generated, so you can write these Rd
files by hand.

defaults for DESCRIPTION entries.

Changes from Markus Muller, excludePattern argument to package.skeleton.dx

Suggestion from Mark Thyer to not put a return after EVERY comma in
the usage section. Instead, we parse the expression and use format to
add line breaks.

== 1.8, 21 Oct 2011

Remove inlinedocExample<- since this was deprecated and now giving a
WARNING on package check.

Take \author for Rd files from Author: section of DESCRIPTION, instead
of Maintainer: section.

bugfix for getSource, for R CMD check with R.2.14.

== 1.7

blank lines allowed after value comments.

usage section broken over lines in modify.Rd.file for prettying pdf
output.

bugfix for when there are no objects defined in the
package. previously forall functions would stop with an error, now we
test for this condition before the line where we would get the error.

getSource(FUN) function from Duncan Murdoch used to extract function
source code, instead of attr(FUN,"source") for compatibility with
R>=2.14.

== 1.6

Only do R CMD check in tests when we run interactively. If not
CRAN/R-Forge gives a weird error.

Remove support for examples.after.return.

Multiparagraph descriptions and unit test.

Description before unit test.

Suppress warnings when we attempt to detach loaded packages, in order
to avoid these warnings:

> warnings()
Warning messages:
1: In FUN(X[[2L]], ...) :
  Created a package name, "2011-05-11 14:11:30", when none found
2: In FUN(X[[2L]], ...) :
  Created a package name, "2011-05-11 14:11:30", when none found
...

Fix warning when S4 classes are defined in package code, by setting
the .packageName variable in the env in apply.parsers, so we don't get
this warning anymore

Warning in getPackageName(where) :
  Created a package name, "2011-04-07 15:29:30", when none found

== 1.5.1

Bugfix for S4 classes by setting the globalenv in apply.parsers to the
env where we eval the pkg code. We were getting this error

Error in assign(mname, def, where) : 
  cannot add bindings to a locked environment

== 1.5

Check to make sure we are not extracting too many documentation
objects, relative to the stored .result in unit tests.

.names such as .s3method and .overwrite in inner documentation lists
are ignored for find/replacement.

.overwrite signals that all other items of the list should be used
when combining, ignoring previous values stored in those slots.

##sections<< permitted immediately after ###return value

Report which of the users' documentation objects we failed on if the
Parser Function in forall stops with an error.

bugfix: for paren matching heuristic in prefixed.lines Parser
Function, do not consider parens in comments.

extended unit tests: now every testfile is assembled into a package
that will be checked using R CMD check. If there are any warnings,
then we will stop with an error. this poses problems for testfiles
with extensive dependencies and references (such as
scatterplot.R). For these, just set the .dontcheck variable in the
testfile.

== 1.4 unit tests for Parser Functions using inst/testfiles/*.R and
the .result variable in each. we check first if all contents of
.result are correctly extracted, then we check to make sure nothing
more is extracted. This should ensure API stability.

== 1.3 Bug fixes and new code contributed by Ph. Grosjean
  
* examples.after.return is modified to detect where examples start using a
  specific mark (either ##examples<<, or #{{{examples). This way, it does not
  get trap with multiple return() in the function, or the presence of a
  return() in the examples

* examples.in.attr parser is added. It look at an "ex" attribute containing
  code of the examples, either as a character string, or as a function.
  
* Added dependence to 'utils' package (for things like package.skeleton())

* Added the possibility to build a NAMESPACE (argument namespace in
  package.skeleton.dx()). A NAMESPACE is also added to the inlinedocs package.
  
* When DESCRIPTION file is empty, fill required fields with reasonable values,
  e.g., Package: with the same name as dir, Version: 1.0-0, etc.
  
* Automatic detection of S3 methods added, and correct formatting of usage and
  addition of entries in NAMESPACE as required.
  
* Reformatting of special cases usages, like fun<-(x, value) => fun(x) <- value,
  met<-.obj(x, ..., value) => method{met}{obj}(x, ...) <= value, and
  %op%(e1, e2) <- e1 %op% e2
  
* Now the packages in the imports field are considered too, as well for building
  the NAMESPACE file
  
* If there is an 'encoding' field in DESCRIPTION, it is now taken into account
  (according to Writing R Extensions manual, it applies to to R code)!
  
* There is now the possbility to place external examples elsewhere
  that in /tests. Just indicate the subdirectory wher you place them
  in options(inlinedocs.exdir = "exsubsir")

* The names of .Rd files was not computed correctly when functions
  with names like `obj<-`, or `%op%`. Corrected.
  
* The presence of platform specific code in /R/unix or /R/windows is
  not supported by inlinedocs (currnetly). However, this was ignored
  silently. Now, package.skeleton.dx() stops process when it find one
  of these subdirs.
  
* A couple of error messages where badly formatted when they included several
  items like in stop("Need ",names(f)[f]," in ",descfile). Corrected.
  
* Wrong extraction of package names form 'Depends' field in case where packages
  contain one or more dots in their names. Corrected.

* It is necessary to eliminate 'R' from the list of packages to load from
  'Depends' field. Corrected.

* package.skeleton.dx() tried to load packages already laoded, and failed to
  unload packages (including their namespaces, if possible) that where not
  loaded before exiting. Corrected.

== 1.2 new code contributions from thomas, extension mechanism using
Parser Function list

== 1.1 
fixed ... argument bug

== 1.0 


root@r-forge.r-project.org
ViewVC Help
Powered by ViewVC 1.0.0  
Thanks to:
Vienna University of Economics and Business Powered By FusionForge