---

Revision 394 - (view) (download) (annotate) - [select for diffs]
Added Mon Dec 23 15:36:20 2013 UTC (4 years, 6 months ago) by markus
File length: 184 byte(s)

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;-))