SCM

SCM Repository

[inlinedocs] Log of /pkg/inlinedocs/inst/testfiles/mm
ViewVC logotype

Log of /pkg/inlinedocs/inst/testfiles/mm

View Directory Listing Directory Listing


Sticky Revision:

Revision 396 - Directory Listing
Modified Tue Feb 18 13:07:32 2014 UTC (4 years, 7 months ago) by markus
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

Revision 394 - Directory Listing
Added Mon Dec 23 15:36:20 2013 UTC (4 years, 9 months ago) by markus
0.) This is an intermediate commit, that will be followed by further tidying. I just got afraid to have to merge branches if I wait longer.

1.) The purposes of the committed changes are 
    a)
    	to enable unittesting for very small units (functions) with the help of a unit testing framework.
    b) 
    	to enable the detailed documentation of S4 methods in separate (signature specific) .Rd files and 
    

2.) Details:
    a) Unittesting:
    	Motivation:
		To implement the changes mentioned above I needed a facility to test very small parts of inlinedocs infrastructure.
    		Just comparing results of all parts combined actions as in the already existent testcases 
    		turned out to be to fragile for my limited understanding of how inlinedocs parts work. 
    		Instead of hoping that package.skeleton.dx would still work after my change and having to write
    		a rather complete result fixture I needed something that would test single functions against a very small 
    		fixture in order to learn what part they were intended to play or how they would have to be tweeaked.
	Existing test tools:
    		Unfortunately it turned out that neither "Runit" nor "testthis" could be applied to test inlinedocs.
    		The reason is that the crucial requirement of test independence was not fulfilled:
    		I was horrified to notice that in both frameworks a test could be reproducibly triggered to fail 
		by code in \emph{another} test.
    		I could  make out a combination of three factors that lead to this unexpected result:
    		- the use of global options and the (necessary) use of environments in inlinedocs
    		- the inability of both testframeworks to isolate such acrobatic behavior to a single test although 
    		  the execution of tests in separated environments is even advertised (in both frameworks!)
    		- the inability of R (at least as far as I know) to provide testframeworks with means of effective isolation
	Adapted test tool:	
    		To make \emph{independent} testing of units possible I went to the rather extreme measure of using a subprocess
    		for each test. The machinery is implemented in  
    		
    		.../testfiles/mm/isolatedTestRunner.R
    		
    		When a test is executed the following things happen:
    		- inside the ...testfiles/mm/tmp a directory is created that reflects the name of the testfunction
    		- source code for a RUnit testsuite (consisting of one test) and a runit.Testfile.R containing the testfunction is created
    		- the suite is run (by means of Rscript ) and the result written to a file 
		  (if it crashes this will be recognized but of course not brake the calling process) 
    		- the result is collected by the isoloatedTestRunner and reported in a very preliminary fashion by isolatedTestrunner.
    		  (RUnit is also used on this level, but could be used more intensly to achieve the same level of reporting and ease of use)
		
		To run all tests just call ./isall.R
		For a single test run use  ./Itest
		Both look nearly like typicla RUnit testsuite with the tiny differece of calling the isolatedTestRunner.R

    	Proposed use:
		For future versions of inlinedocs I strongly recommend a mandatory  extensive testsuite but for the moment 
    		I confined all my unittesting in the directory:

    		.../testfiles/mm

    		because I of course need your agreement, dispute,  opinion or advise for such a change of infrastructure.
                
		At the moment I would just be happy if you run:

		isall.R 	in 

		inlinedocs/inst/testfiles/mm/
		
		before you commit, to see I some of the new tests are broken.



   b) Method documentation:
   	For a generic with the name "GenericName" and the signature c("ClassNameA","ClassNameB") a file with the name GenericName-method-#ClassNameA#ClassNameB.Rd
	is created and populated using the same infrastructe that is used for functions for the actual definition, but a rather different approach
	to find the Generic (forGeneric is not similar enough to forFun to use forAll in both cases)
	I am still struggeling with documentation of operator methods since for them no "srcref" attribute seems to be available but I am working on this.
	
Next Steps and Proposal:
complete operator method description and cleanup (e.g. check if inlinedocs package itself still builds an passed cran checks;-))
 

		

	   

     	






Sort log by:

R-Forge@R-project.org
ViewVC Help
Powered by ViewVC 1.0.0  
Thanks to:
Vienna University of Economics and Business University of Wisconsin - Madison Powered By FusionForge