docattr: Flat-format documentation

In mvbutils: General utilities, workspace organization, code and doc editing, live package maintenance, etc

Flat-format documentation

Description

The docattr convention, and its obsolete ancestor flatdoc, lets you edit plain-text documentation (or other plain-text attributes) in the same file as your function's source code. You can add docattr yourself; in the full mvbutils scheme, that's rarely done explicitly, but you will see them in text files produced by fixr. They are mostly used to write Rd-style help with almost no markup (much cleaner than Roxygen!) that will be converted into Rd-format when building/exporting packages. However, mvbutils extends help so that ?myfunc will display plain-text documentation for myfunc, even if myfunc isn't in a package. There are no restrictions on the format of informal-help documentation, so docattr is useful for adding quick simple help just for you or for colleagues. If your function is to be part of a maintained package (see mvbutils.packaging.tools), then the documentation should follow a slightly more formal structure; use fixr( myfun, new.doc=T) to set up the appropriate template.

A neat trick, for a function where you want "internal" documentation but not visible (yet), is to name the attribute "secret_doc" rather than "doc".

The difference between these two functions is that docattr (which requires R >= 4.1) has completely regular R syntax, taking advantage of "raw strings" (see Quotes). flatdoc had to use a rather devious trick which required that the file was subsequently read in by source.mvb rather than source. If you have a task package wundapak which uses flatdoc, then you can convert it with eg tidyup_docattr(..wundapak).

docattr is a simple wrapper for string2charvec, to which it just adds the "docattr" class so that the documentation is not printed by default; you will just see "# FLAT-FORMAT DOCUMENTATION" appended to the function body.

Usage

# ALWAYS use it like this:
# structure( function( ...) {body},
# doc=docattr( r"--{
#... including newlines, etc}--
# }--"))
# almost NEVER like this
docattr( rawstr)
# Obsolete flatdoc() version
# ALWAYS use it like this:
# structure( function( ...) {body},
# doc=flatdoc( EOF="<<end of doc>>"))
# plaintext doco goes here...
# NEVER use it like this:
flatdoc( EOF="<<end of doc>>")
tidyup_docattr( e)

Arguments

rawstr	a single string, almost certainly a raw string containing the plain-text documentation.
EOF	character string showing when plain text ends, as in readlines.mvb
body	replace with your function code
...	replace with your function arg list
e	an environment (usually a task package, starting with ..— but it could be .GlobalEnv), or the name of an environment.

Value

docattr returns a character vector of class docattr. The print method for docattr objects just displays the string "# FLAT-FORMAT DOCUMENTATION", to avoid screen clutter.

Internal details of flatdoc

This section can be safely ignored by almost all users, and as of mvbutils v2.11.0, it's obsolete anyway since docattr should now replace flatdoc throughout.

On some text editors, you can modify syntax highlighting so that the "start of comment block" marker is set to the string "doc=flatdoc(".

It's possible to use flatdoc to read in more than one free-format text attribute. The EOF argument can be used to distinguish one block of free text from the next. These attributes can be accessed from your function via attr( sys.function(), "<<attr.name>>"), and this trick is occasionally useful to avoid having to include multi-line text blocks in your function code; it's syntactically clearer, and avoids having to escape quotes, etc. mvbutils:::docskel shows one example.

fixr uses write.sourceable.function to create text files that use the flatdoc convention. Its counterpart FF reads these files back in after they're edited. The reading-in is not done with source but rather with source.mvb, which understands flatdoc. The call to doc=flatdoc causes the rest of the file to be read in as plain text, and assigned to the doc attribute of the function. Documentation can optionally be terminated before the end of the file with the following line:

  <<end of doc>>

or whatever string is given as the argument to flatdoc; this line will cause source.mvb to revert to normal statement processing mode for the rest of the file. Note that vanilla source will not respect flatdoc; you do need to use source.mvb.

flatdoc should never be called from the command line; it should only appear in text files designed for source.mvb.

The rest of this section is probably obsolete, though things should still work.

If you are writing informal documentation for a group of functions together, you only need to flatdoc one of them, say myfun1. Informal help will work if you modify the others to e.g.

  myfun2 <- structure( function(...) { whatever}, doc=list("myfun1"))

If you are writing with doc2Rd in mind and a number of such functions are to be grouped together, e.g. a group of "internal" functions in preparation for formal package release, you may find make.usage.section and make.arguments.section helpful.

Author(s)

Mark Bravington

See Also

doc2Rd, dochelp, write_sourceable_function, source.mvb,

make.usage.section, make.arguments.section, fixr,

the demo in "flatdoc.demo.R"

Examples

# This illustrates the general format for a function with attached plain-text
# documentation. It is the format produced by write_sourceable_function()
flubbo <- structure( function( x){
  ## A comment
  x+1
}
,doc=mvbutils::docattr( r"-{
flubbo       not-yet-in-a-package
'flubbo' is a function! And here is some informal doco for it. Whoop-de-doo!
See "sample.fun.rrr" in the "demostuff" folder for a better example, with full paragraphs.
I have had to shorten this one to appease the CRANia.
}-")
)
# Here is one way to add a text attribute to a function:
myfun <- structure( function( myname){
  texto <- attr( sys.function(), 'text')
  sprintf( texto, myname)
}
, text= mvbutils::docattr( r"--{
It's all about \%s!
The "universe" 'revolves' around \%s!
}--"))
myfun( 'potatoes')
## Don't run
## OBSOLETE: 'flatdoc' itself is superceded by 'docattr'
## Put next lines up to "<<end of doc>>" into a text file <<your filename>>
## and remove the initial hashes
#structure( function( x) {
#  x*x
#}
#,doc=flatdoc("<<end of doc>>"))
#
#Here is some informal documentation for the "SQUARE" function
#<<end of doc>>
## Now try SQUARE <- source.mvb( <<your filename>>); ?SQUARE
## Example with multiple attributes
## Put the next lines up to "<<end of part 2>>"
## into a text file, and remove the single hashes
#myfun <- structure( function( attname) {
#  attr( sys.function(), attname)
#}
#,  att1=flatdoc( EOF="<<end of part 1>>")
#,  att2=flatdoc( EOF="<<end of part 2>>"))
#This goes into "att1"
#<<end of part 1>>
#and this goes into "att2"
#<<end of part 2>>
## Now "source.mvb" that file, to create "myfun"; then:
# myfun( 'att1') # "This goes into \\"att1\\""
# myfun( 'att2') # "and this goes into \\"att2\\""
## End don't run

mvbutils documentation built on May 25, 2026, 5:09 p.m.