Skip to content

Minor omissions/imprecisions in AutoDoc() function documentation #163

@gwhitney

Description

@gwhitney
  1. The argument list for AutoDoc() in the manual implies that if the package parameter is omitted, the optrec must be as well, but that's not the case.

  2. The list of tasks AutoDoc() can perform omits the creation of maketest.g.

  3. The package parameter serves to determine both the package directory in which AutoDoc() will operate and the metadata for the package being documented. It would be useful to clarify this point and explain exactly how those two pieces of information are determined in each of the three cases for the parameter (a string, an IsDirectory, or omitted).

  4. It would also be nice for completeness to say how those two things are determined in the worksheet case, since the documentation for AutoDocWorksheet() primarily just refers to the AutoDoc() documentation.

  5. The documentation for the dir entry of the options record hints at the fact that a string value for that option must always be relative to the package directory. It would be useful to emphasize/clarify this point, and also to document that this is not only where documentation files like GapDoc XML will be found, but also where all files will be generated.

I will momentarily submit a pull request with suggested resolutions of these (admittedly minor) items. The motivation for filing this issue and pull request at all is that I also believe there is a bug with using an absolute dir (in the form of an IsDirectory object) in the options record at all, and I plan shortly to submit an issue for that bug and a pull request resolving it, but it seemed necessary to document the apparently intended behavior of that parameter and related issues first. If I've misunderstood the intended behavior of AutoDoc(), my apologies and of course that should be taken into account in evaluating the subsequent issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions