Every function and class in the current directory is written afresh, along with the members of each class and the contents of any +pkg or @class directory below it, and any entry that no longer corresponds to a file is dropped. A doc-cache is a per-directory file, so this is the whole of one, which is what makes it the unit worth having: a directory rebuilt this way is in the state a full package rebuild would leave it in.

The current directory must be a function directory of a package, so a package root, a +pkg or @class directory, and private, tests, demos or datasets are all refused, the middle two because their cache could be read by nothing.

'-auto' narrows the work to what git reports as changed within this directory, and is the form to reach for while working in one: a directory holding many classes takes minutes to rebuild whole and seconds to refresh for the two files just edited. Where there is no git to ask, or the tree is not a repository, it is ignored with a warning and the whole directory is rebuilt, which is what would have been asked for had the question been answerable. A file that moved between directories is only half of its own rename here, the departure seen in the directory it left and the arrival in the one it joined, so run it in both or reach for package_texi2cache instead.

'-check' writes nothing and reports what would change, and may be given together with '-auto' to ask whether the files just edited are already accounted for.

options is a pkg_doc_options object. Unlike the per-item functions, an INDEX given through it decides what is cached: only the names it lists are written, so the cache holds the package’s public surface rather than whatever the directory happens to carry. A name found here but absent from INDEX is skipped and reported. An INDEX entry answering to no file is not reported at this scope, since a directory cannot tell one naming a file elsewhere from one naming nothing at all.

report is a struct with the fields 'cache', 'added', 'updated', 'removed', 'changed' and 'findings'. With no output requested the same information is printed.

See also: package_texi2cache, classdef_texi2cache, function_texi2cache, pkg_doc_options

Source Code: folder_texi2cache