mvbutils (version 2.5.4)

dochelp: Documentation

Description

dochelp(topic) will be invoked by the replacement help if conventional help fails to find documentation for topic topic. If topic has a doc attribute, the latter will be formatted and displayed by file.show. dochelp is not usually called directly.

Usage

# Not usually called directly
# If it is, then normal usage is: dochelp( topic)
dochelp( topic, doc)

Arguments

topic

(character) name of the object to look for help on.

doc

(character or list)-- normally not set, but deduced by default from topic; see Details.

Details

dochelp will only be called if the original help call was a simple help(topic=X,...) form, with X not a call and with no try.all.packages or type or lib.loc arguments (the other help options are OK). The doc argument defaults to the doc attribute of get("topic"). The only reason to supply a non-default argument would be to use dochelp as a pager; this might have some value, since dochelp does reformat character vectors to fit nicely in the system pager window, one paragraph per element, using strwrap. Elements starting with a "%" symbol are not displayed. To work with dochelp, a doc attribute should be either:

• a character vector, of length >=1. New elements get line breaks in the pager. Or:
• a length-one list, containing the name of another object with adocattribute.dochelpwill then use thedocattribute of that object instead. This referencing can be iterated.

If the documentation is very informal, start it with a blank line to prevent find.documented( ..., doctype="Rd") from finding it. The file will be re-formatted to fit the pager; each paragraph should be a single element in the character vector. Elements starting with a % will be dropped (but may still be useful for doc2Rd). flatdoc offers an easy way to incorporate plain-text (flat-format) documentation-- formal or informal-- in the same text file as a function definition, allowing easy maintenance.

See Also

flatdoc, doc2Rd, find.documented, strwrap

Examples

myfun <- structure( function() 1,
  doc="Here is some informal documentation for myfun\n")
dochelp( "myfun")
help( "myfun") # calls dochelp