code.consxy.com Git - sheep/blob - docs/Reference.md

   1 # Package SHEEP
   2
   3 Main sheep package.
   4
   5 Use sheep to validate that documentation strings on external symbols adhere to a strict format and exist, so that they can be output to markdown format, while looking decent when used within a common lisp process.
   6
   7 ## Contents
   8
   9 * **function [export-package](#function-export-package)** - _export-package_ takes in _pkg_ and converts all the documentation for the symbols into markdown with the hope of emulating the hyperspec style.
  10 * **function [pretty-print-validate-packages](#function-pretty-print-validate-packages)** - _pretty-print-validate-packages_ takes _pkgs_ and runs validation on all of them. It dumps to standard out failures as it comes upon them, finally returning whether it was successful or not.
  11 * **function [validate-package](#function-validate-package)** - _validate-package_ takes in _pkg_ and validates that all the external symbols adhere to documentation guidelines, exist, and can be parsed to be used for exporting.
  12 * **condition [validation-failure](#condition-validation-failure)** - Used internally for sheep parts to signal a validation error.
  13
  14 ## Function **EXPORT-PACKAGE**
  15
  16 #### Syntax:
  17
  18 **export-package** _pkg_ => _markdown_
  19
  20 #### Arguments and Values:
  21
  22 _pkg_---A package symbol
  23 _markdown_---A string containing the markdown representation of this packages documentation
  24
  25 #### Description:
  26
  27 _export-package_ takes in _pkg_ and converts all the documentation for the symbols into markdown with the hope of emulating the hyperspec style.
  28
  29 It should only be run after the package has been validated, as it assumes that all documentation it gets will be valid.
  30
  31 ## Function **PRETTY-PRINT-VALIDATE-PACKAGES**
  32
  33 #### Syntax:
  34
  35 **pretty-print-validate-packages** _&rest_ _pkgs_ => _success_
  36
  37 ```pkgs::= pkg*```
  38
  39 #### Arguments and Values:
  40
  41 _success_---Whether or not all symbols passed validation
  42 _pkg_---A package symbol
  43
  44 #### Description:
  45
  46 _pretty-print-validate-packages_ takes _pkgs_ and runs validation on all of them. It dumps to standard out failures as it comes upon them, finally returning whether it was successful or not.
  47
  48 This can be used in validation tests to ensure that documentation can be generated at a later date.
  49
  50 #### Examples:
  51
  52 ```(pretty-print-validate-packages :pkg1 :pkg2)``` => ```t```
  53
  54 ## Function **VALIDATE-PACKAGE**
  55
  56 #### Syntax:
  57
  58 **validate-package** _pkg_ => _failures_
  59
  60 ```failures::= failure*```
  61 ```failure::= (:failure symb msg)```
  62
  63 #### Arguments and Values:
  64
  65 _pkg_---A package symbol
  66 _symb_---Symbol the check failed on
  67 _msg_---Message containing information about the failure
  68
  69 #### Description:
  70
  71 _validate-package_ takes in _pkg_ and validates that all the external symbols adhere to documentation guidelines, exist, and can be parsed to be used for exporting.
  72
  73 Only one error per symbol will be reported at a time, all concatenated to a list in the aforementioned form.
  74
  75 ## Condition VALIDATION-FAILURE
  76
  77 Used internally for sheep parts to signal a validation error.