NAME

R::Comment2DocDraft - transform comments in R code to .rd doc files

SYNOPSIS

  use R::Comment2DocDraft;
  
  R::Comment2DocDraft->draft("single.R");
  R::Comment2DocDraft->draft("R/");
  R::Comment2DocDraft->draft("single.R", author => 'Zuguang Gu <jokergoo@gmail.com>');

or by command line:

  r-comment2docdraft single.R
  r-comment2docdraft R
  r-comment2docdraft single author "Zuguang Gu <jokergoo@gmail.com>"

DESCRIPTION

When I am writing an R package, I find writing documents in man/ dir is really boring. You need to tolerate hundreds of braces and be cautious to make sure all the braces are matched correct. Also you need to add spaces at the begining of some lines and make each line containing approximately 80 characters. The more you are trying to make your tex code beautiful, the more chaos you will meet. If there are some words need to be marked such as a \code{\link[]{}} mark, the code would be difficult to read. Morever, if you change the function arguments in .R file, I always forget chagne the corresponding part in .rd files. It produces a lot of errors when checking the R package.

The R docs are written in LaTex format. Well, it is not friendly enough for human to read. Also, seperating docs from codes is not convinient for maintaining the package. A good way is to put the docs as comments with the code. With some appointed simple formats, the comments would be easy to read and easy to convert to docs as well.

The idea is inspired by javadoc and MarkDown.

The module just produces a draft of .rd file because some sections are not proper to be put in the comment such as the example section. So users should edit the .rd file afterwards.

The format of the comment is really simple. The first line is the section name and from the second line is the section content. such as

  # title:
  #   A function to calculate mean value

For some obsessive aesthetics, there should be one space in front of the section name and three spaces in front of the section content. Note that the colon is necessary since we identify section name by it. Functions should follow corresponding comments because we need to read the function names and the function args.

There are some sections I think informative in comments. The list is title, description, arguments, details, value, author, references, source, seealso. Also name and docType should be added in data and package docs. Except title section, all other sections are optional.

Sections

Some sections do not need be set at every comment, such as author or references. This kind of information can be set as a global variables. See draft secton.

text transformation

`function` will be converted to \code{\link{function}}

`package::function` will be converted to \code{\link[package]{function}}

``argument`` will be converted to \code{argument}

http|ftp|https:://xxx will be converted to \url{http|ftp|https://xxx}

title

Example is:

  # title:
  #   this is a function title

It will be converted as \title{content}. The title section should be places as the first line of your comment to inform that the comment should be converted.

description

Example is:

  # description
  #   this is description, paragraph1
  #
  #   this is description, paragraph2

It will be converted as \description{content}.

usage

For function, the function name and the function args would be parsed from source code, so users do not need to set it.

arguments

Example is:

  # arguments:
  #   x first argument
  #   y second argument
  #   z third argument, line1,
  #     third argumetn, line2

It will be converted to

  \arguments{
    \item{x}
      {first argument}
    \item{y}
      {second argument}
    \item{z}
      {third argument, line1, third argument, line2}
  }

Note we do not do any checking on the item list and the arguments in the function.

details

Example is:

  # details:
  #   this is a details, paragraph1
  #
  #   this is a details, paragraph2

It will be converted to

  \details{
    this is a details, paragraph1
    
    this is a details, paragraph2
  }

value, value list

Example is:

  # value:
  #   the function returns a list
  #
  # valuelist:
  #   x vector
  #   y vector

It will be converted to

  \value{
    the function returns a list
    \item{x}{vector}
    \item{y}{vector}
  }

source

Example is:

  # source:
  #   http://url1
  #   http://url2

It will be converted to

  \source{
    \url{http://url1}
    
    \url{http://url2}
  }

author

Example is:

  # author:
  #   jokergoo <at> gmail.com

It will be converted to

  \author{
    jokergoo <at> gmail.com
  }

references

Example is:

  # references:
  #   ref1
  #   ref2

It will be converted to

  \references{
    ref1
    
    ref2
  }

seealso

Example is:

  # seealso
  #   `function1`, `function2`, `package::function3`

It will be converted to

  \seealso{
    \code{\link{function1}}, \code{\link{function2}},
    \code{\link[package]{function3}}
  }

Subroutines

draft(file|dir, sectionname, sectionvalue, ...)

The first parameter should be either a filename or a dir containing a list of R files. the remaining parameters should be written as paris. The remaining parameters can be thought of some global information such as author or references. But just make sure the section name you set is a valid name since the module does not do this kind of checkings. That will be checked by the R engine.

Command line

r-comment2docdraft command is similar to draft function. The first argument is either a filename and a dir. other argument will be passed as section name and section value.

  r-comment2docdraft single.R
  r-comment2docdraft R
  r-comment2docdraft single.R author "Zuguang Gu <jokergoo@gmail.com>"

TODO

convert comment mixed with paragraph and list.

if there already exist doc files, just update sections that have been changed.

AUTHOR

Zuguang Gu <jokergoo@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2012 by Zuguang Gu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12.1 or, at your option, any later version of Perl 5 you may have available.