doc(x = Y) searches for documentation of the object Y.  The documentation is either an html document on the hard drive of the current computer, or it is an R string vector in a file on the search path.  doc(x = Y) searches for an html document, Y.htm or Y.html, in one of the folders described in the DETAILS section below.  If html documentation is found at one of these locations, then Y.htm will be loaded into the browser specified by options("browser").  If no html documentation is found, then doc searches for an object named <object.name.doc>; e.g., if no html documentation exists for Y, then  doc(x = Y) searches for a string vector named Y.doc in a file on the search path.  If it is found, then it will be written to the computer monitor.  As long as the html argument of doc is set to TRUE (the default), the html documentation will take precedence over a documentation string, e.g., if Y.htm exists in an appropriate directory and if Y.doc exists in a file on the search path, then Y.htm will be loaded into the browser and the Y.doc string will be ignored.  

function (
x, 
html            = TRUE, 
suppress.o.type = FALSE, 
widthX          = 1, 
doc.directory   = NA,
setBrowser      = "docDefault",
show.html.path  = FALSE,
display.long    = FALSE  ) 
#

ARGUMENTS:

x: x must be an object with either html documentation on the computer's hard drive, or an object with a doc attribute or else there must exist a x.doc object on the search path.  Optionally x can be the name of a string, e.g., x = aaa.doc where aaa.doc is a character string (typically documentation of some kind).  

html: If html = TRUE (default), then html documentation will be loaded into the designated browser if it can be found.  If no html documentation is found, then .doc documentation is printed to the computer screen if it can be found.  If neither html nor .doc documentation is found for x, then an error message is produced.  If html = FALSE, then html documentation is ignored, whether or not it exists, and .doc documentation is printed to the computer screen if it can be found.  If .doc documentation is not found for x, then an error message is produced.  

suppress.o.type: Set suppress.o.type = TRUE to suppress the display of the object type (o.type function output).  If suppress.o.type = FALSE, then the information regarding the object type is printed to the display.  

widthX: widthX can be used to alter the proportion of the screen width that is covered by a line of text before it begins to wrap.  The default is widthX = 1.0.  This only applies if .doc documentation is printed to the computer screen.

doc.directory: The doc function searches for html documentation in a series of directories.  If the doc.directory argument designates a directory, then this directory is the first file to be searched for html documentation.  If doc.directory = NA, then other directories are searched for html documentation.  These other directories are described in the DETAILS section below.  

setBrowser: If setBrowser = "docDefault" (default), then the doc function looks for a string or functioned named docBrowser on the search path.  If a function named docBrowser is on the search path, doc expects docBrowser() to return a string that designates a browser program, .e.g., docBrowser() = "C:\\Program Files (x86)\\Mozilla Firefox\\firefox.exe".  Alternatively, if a string named docBrowser is found, doc expects it to name a browser program (including its path).   In either case, html documentation will be loaded into this browser.  If no docBrowser function or string is found, then html documentation will be loaded into the default browser specified by getOption("browser").  When getOption("browser") = NULL, the default browser is the default browser for the current operating system.  If setBrowser is not "docDefault", then it should be set to a string that specifies a browser program.  

show.html.path: If show.html.path = TRUE, the output shows the path+file names that were checked for html documentation.  If show.html.path = FALSE (default), then this output is omitted.  

display.long: If display.long = FALSE (default), a string vector whose combined length exceeds 10,000 characters will be truncated at 10,000 characters together with an explanation for what has happened.  If display.long = TRUE, a string vector will be displayed in its entirety regardless of how long is its combined length.  The "combined length" of a string vector str refers to the value of nchar(paste(str, collapse = " ")).  The main use of the display.long argument is to avoid ugly displays which can happen when the doc function is erroneously applied to a string matrix that has no documentation, e.g., doc(Mat) where Mat is a string matrix where nchar(paste(str, collapse = " ")) > 100,000.  

DETAILS
Obviously, html documentation exists for an object only if the user has created it.  The html documentation can take any form as long as it can be loaded into the default browser on the current computer.  The doc function looks for html documentation in the following locations:

1:: The doc.directory argument of doc is set either  to a function whose value is a string, or to a string, or it is missing (NA).  If doc.directory is a function, then doc.directory() must yield a string that names a directory in which html documentation may be found.  If the doc.directory is a string, then it must name a directory at which html documentation may be found.  If doc.directory is missing (default), then this argument is ignored.  The function version of doc.directory is useful if different directories are specified depending on the context in which the doc function is called.  The directory specified by doc.directory is the first position on the doc search path to be searched for html documentation for the object x.  

2:: doc uses the find function to find the first file on the search path that contains the object, e.g., if the function call is doc(x = Y), then a call to find("Y") is made.  If Y is found in a file on the search path that has the form "file:<string>" where string contains at least one separator of the form "/" or "\\", then the path and directory PATH is extracted from <string>.  doc searches for a file of the form Y.htm or Y.html in the directory specified by PATH and also in a possible subdirectory, PATH\rdoc.  

3:: doc.directory.local is not an argument of the doc function.  Rather the doc function looks for an object named doc.directory.local in the same file as x.  E.g., if the call is to doc(x = Y), then doc determines the name of the first file on the search path that contains an object named "Y" (the object must also be of the same mode as Y), and it looks for doc.directory.local in this file.  If doc.directory.local is a function, then doc.directory.local() must yield a string that names a directory in which html documentation may be found.  If the doc.directory.local is a string, then it must name a directory at which html documentation may be found.  If doc.directory.local is missing (default), then doc proceeds without specifying doc.directory.local.  The function version of doc.directory.local is useful if different directories are specified depending on the context in which the doc function is called.  The directory specified by doc.directory.local is the second position on the doc search path to be searched for html documentation for the object x.   

4:: The current working directory, getwd(),  is searched for html documentation.  In addition, doc checks whether the current working directory has a subdirectory named rdoc.  If it does, this subdirectory is also searched for html documentation.  

5:: If an rdoc subdirectory exists beneath the directory that contains the file that contains the doc function, then it is searched for html documentation.