SCM

SCM Repository

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

Log of /pkg/inlinedocs/inst

View Directory Listing Directory Listing


Sticky Revision:

Revision 396 - Directory Listing
Modified Tue Feb 18 13:07:32 2014 UTC (5 years, 3 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
Modified Mon Dec 23 15:36:20 2013 UTC (5 years, 4 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;-))
 

		

	   

     	






Revision 393 - Directory Listing
Modified Tue Oct 1 07:15:26 2013 UTC (5 years, 7 months ago) by tomaschwutz
fixed error in parsing examples with (yet) empty lines

Revision 389 - Directory Listing
Modified Tue Sep 3 04:33:09 2013 UTC (5 years, 8 months ago) by tdhock
copy utils code to utils.R to avoid utils::: and pass R CMD check

Revision 387 - Directory Listing
Modified Thu Aug 22 09:28:21 2013 UTC (5 years, 8 months ago) by tdhock
update JSS citation

Revision 385 - Directory Listing
Modified Tue Jul 23 00:24:56 2013 UTC (5 years, 9 months ago) by tdhock
bibentry typo

Revision 384 - Directory Listing
Modified Tue Jul 23 00:18:14 2013 UTC (5 years, 9 months ago) by tdhock
cran asked for update

Revision 376 - Directory Listing
Modified Mon Jan 28 01:08:01 2013 UTC (6 years, 3 months ago) by tdhock
version 1.9.2 bugfixes

Revision 367 - Directory Listing
Modified Thu Oct 25 10:07:37 2012 UTC (6 years, 6 months ago) by tomaschwutz
tryCatch around parse in gen.Rd, workaround on accessor functions failures

Revision 347 - Directory Listing
Modified Fri Apr 6 08:41:22 2012 UTC (7 years, 1 month ago) by tdhock
apply testfile for \code{+} +jss article

Revision 336 - Directory Listing
Modified Thu Apr 5 12:44:33 2012 UTC (7 years, 1 month ago) by tdhock
do.not.generate example, partial arg NOTEs fixed

Revision 333 - Directory Listing
Modified Mon Mar 12 12:12:39 2012 UTC (7 years, 2 months ago) by tdhock
do not escape percents in inlinedocs nor in doc lists

Revision 322 - Directory Listing
Modified Mon Jan 30 07:54:36 2012 UTC (7 years, 3 months ago) by tdhock
citation file

Revision 319 - Directory Listing
Modified Fri Jan 13 20:57:04 2012 UTC (7 years, 4 months ago) by tdhock
need desc for no warn

Revision 318 - Directory Listing
Modified Fri Jan 13 20:49:00 2012 UTC (7 years, 4 months ago) by tdhock
make example executable

Revision 315 - Directory Listing
Modified Fri Jan 13 15:56:20 2012 UTC (7 years, 4 months ago) by tdhock
escape percent example

Revision 310 - Directory Listing
Modified Mon Oct 31 16:32:47 2011 UTC (7 years, 6 months ago) by tdhock
google inline examples

Revision 307 - Directory Listing
Modified Fri Oct 21 11:37:19 2011 UTC (7 years, 6 months ago) by tdhock
test errors reported more clearly

Revision 304 - Directory Listing
Modified Tue Jul 19 17:03:18 2011 UTC (7 years, 10 months ago) by tdhock
doc usage line breaks, works under R-2.13.1

Revision 270 - Directory Listing
Modified Mon May 23 15:53:47 2011 UTC (7 years, 11 months ago) by tdhock
delete examples.after.return support

Revision 259 - Directory Listing
Modified Sun May 1 19:15:09 2011 UTC (8 years ago) by tdhock
definition/news

Revision 258 - Directory Listing
Modified Sun May 1 19:12:41 2011 UTC (8 years ago) by tdhock
description before ex

Revision 257 - Directory Listing
Modified Sun May 1 17:03:01 2011 UTC (8 years ago) by tdhock
multipar desc

Revision 245 - Directory Listing
Modified Thu Apr 7 13:21:08 2011 UTC (8 years, 1 month ago) by tdhock
jss test

Revision 204 - Directory Listing
Modified Fri Feb 18 16:48:22 2011 UTC (8 years, 3 months ago) by tdhock
alternate syntax parser testfile

Revision 176 - Directory Listing
Modified Thu Jan 6 15:26:49 2011 UTC (8 years, 4 months ago) by tdhock
unit test

Revision 160 - Directory Listing
Modified Tue Nov 9 16:52:09 2010 UTC (8 years, 6 months ago) by tdhock
paren ex

Revision 156 - Directory Listing
Modified Fri Oct 29 13:06:55 2010 UTC (8 years, 6 months ago) by tdhock
R CMD check for each testfile

Revision 154 - Directory Listing
Modified Fri Oct 29 12:11:52 2010 UTC (8 years, 6 months ago) by tdhock
parsefun and extract.docs.fun consolidated into extract.xxx.chunks in ongoing effort to make parser functions more readable and modular

Revision 152 - Directory Listing
Modified Thu Oct 28 15:57:51 2010 UTC (8 years, 6 months ago) by tdhock
parsers error catch for s4 classes

Revision 140 - Directory Listing
Modified Tue Oct 19 23:24:01 2010 UTC (8 years, 7 months ago) by tdhock
do ex in tempdir

Revision 138 - Directory Listing
Modified Tue Oct 19 22:51:59 2010 UTC (8 years, 7 months ago) by tdhock
update examples to pass new more stringent parser checks

Revision 135 - Directory Listing
Modified Tue Oct 19 15:43:38 2010 UTC (8 years, 7 months ago) by tdhock
softThreshExAttr ex to tests

Revision 134 - Directory Listing
Modified Tue Oct 19 15:33:23 2010 UTC (8 years, 7 months ago) by tdhock
softThresh ex to tests

Revision 127 - Directory Listing
Modified Mon Sep 20 13:20:59 2010 UTC (8 years, 8 months ago) by tdhock
add scatterplot directlabels unit test

Revision 125 - Directory Listing
Modified Thu Sep 16 09:34:38 2010 UTC (8 years, 8 months ago) by tdhock
extended package.skeleton.dx example that also checks the silly package and verifies that there are no warnings

Revision 123 - Directory Listing
Modified Mon Aug 30 09:19:39 2010 UTC (8 years, 8 months ago) by tomaschwutz
added alias inlinedocs to function package.skeleton.dx (to be displayed on ?inlinedocs)
added an example to package.skeleton.dx
added the silly package to inst directory, so that a package for examples is available at installation time 


Revision 122 - Directory Listing
Modified Sat Aug 28 21:36:48 2010 UTC (8 years, 8 months ago) by tomaschwutz
implemented Claudia's suggestion about the assignment function of example code to attribute ex:
added function inlinedocExample<- in file package.skeleton.dx.R with specifying the example already using this mechanism
added testfile attrExamples.R

in addition added suppressWarnings() around the call to package.skeleton, because it always gave a warning of non-exisiting package with my Windows version of R 10.1.

Revision 118 - Directory Listing
Modified Fri Jun 18 16:32:29 2010 UTC (8 years, 11 months ago) by tdhock
fermat-inline test, extract.docs.fun now uses nondesc.parsers as the parser list

Revision 115 - Directory Listing
Modified Fri Jun 18 10:35:11 2010 UTC (8 years, 11 months ago) by tdhock
silly example unit test checks

Revision 113 - Directory Listing
Modified Fri Jun 18 09:40:30 2010 UTC (8 years, 11 months ago) by tdhock
test.file verbose, tags test, save.test.result doc

Revision 111 - Directory Listing
Modified Mon Jun 7 12:33:37 2010 UTC (8 years, 11 months ago) by tdhock
test for sublogo

Revision 110 - Directory Listing
Added Mon Jun 7 12:08:54 2010 UTC (8 years, 11 months ago) by tdhock
unit test for extract.docs.file

Sort log by:

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