devtools.docLint (TARGET) prints every disagreement it finds between a package’s texinfo blocks and the package itself. TARGET is either the folder a package’s source is in or the name of an installed package, which is looked up with pkg ("list").

R = devtools.docLint (TARGET) prints nothing and returns the findings as a structure array holding file, line, rule and message, empty where there is nothing to report.

Documentation is the one part of a package that never runs, so no test suite reaches it: a name that changed, a cross-reference to something that was removed and a line that grew past the margin all survive every test the package has. These are the checks that can be made mechanically.

'deftypefn-name'

The name a header documents is not the name of the function that follows it, or a function file documents a name other than its own.

'category'

The first brace group of a header is not what it should be: the package for a function, for the block documenting a class and for the constructor of an old-style @class, the class for a classdef constructor, a method and a property. The package is the name in DESCRIPTION, never a namespace, and the class is named in full, prob.BetaDistribution rather than BetaDistribution.

'seealso-target'

An @seealso names something that is not in this package, not in core and not in any package now loaded.

'seealso-member'

An @seealso names a class member without its class. help finds ClassificationTree.margin and does not find margin, so a bare member tells the reader to type something that does not work.

'width'

A texinfo body line is longer than 80 columns. Header lines are exempt, their signatures being allowed to run over, and so is a line holding nothing but a URL, bare or in @url or @uref, and trailing punctuation, a URL having nowhere to break. A URL sharing its line with text is still reported: it moves to a line of its own.

'index-missing'

INDEX lists a name the package does not supply.

'index-unlisted'

The package supplies a function or a class that INDEX does not list. INDEX gates what is cached and published, so an omission is how a name is kept off both; this rule reports them so that the omissions are the ones that were meant.

Skipped throughout are private, tests and demos folders, none of which are a package’s documented surface. Names wrapped in double underscores are internal, so 'index-unlisted' does not report them; every other rule checks them, since help reads them like any other. A cross-reference is resolved against what is on the load path at the time, so a package whose dependencies are not loaded reports references into them as unresolved.

See also: devtools.mcp, devtools.selftest

Source Code: devtools.docLint