# hs.doc.builder

Builds documentation support files. Still experimental.

This submodule provides functions for mimicking the documentation generation processes used when generating the official Hammerspoon documentation. The long term goal is to provide a mechanism for generating complete Hammerspoon documentation in all of its formats with only the Hammerspoon application and source files without any additional software required.

This submodule can be used to generate and maintain the documentation for Spoon bundles and can also be used to generate documentation for third-party modules as well.

Documentation for modules and spoons is expected to be embedded in the source code for the relevant object in specially formatted comment strings. A very brief example of how to format documentation can be found at https://github.com/Hammerspoon/hammerspoon/blob/master/SPOONS.md#documentation, but a better treatment is planned.

Most of this submodule should be considered at the "Proof of Concept" stage and will require some additional work on your part to generate useful documentation in HTML, Markdown, or Docset formats. This is expected to change in the future.

# API Overview

Functions - API calls offered directly by the extension

genComments
genJSON
genSQL

# API Documentation

# Functions

# genComments


Signature	`hs.doc.builder.genComments(path, [recurse]) -> table`
Type	Function
Description	Generates a documentation table for Hammerspoon modules or Spoon bundles from the source files located in the path(s) provided.
Parameters	where - a string specifying a single path, or a table containing multiple strings specifying paths where source files should be examined to generate the documentation table. recurse - an optional boolean, default true, specifying whether or not files in sub-directories of the specified path should be examined for comment strings as well.
Returns	table - a table containing the documentation broken out into the key-value pairs used to generate documentation displayed by `hs.doc` and `hs.doc.hsdocs`.
Notes	Because Hammerspoon and all known currently available modules are coded in Objective-C and/or Lua, only files with the .m or .lua extension are examined in the provided path(s). Please submit an issue (or pull request, if you modify this submodule yourself) at https://github.com/Hammerspoon if you need this to be changed for your addition.
Examples	None
Source	extensions/doc/doc_builder.lua line 37

# genJSON


Signature	`hs.doc.builder.genJSON(source) -> string`
Type	Function
Description	Generates a JSON string representation of the documentation source specified. This is the format expected by `hs.doc` and `hs.doc.hsdoc` and is used to provide the built in documentation for Hammerspoon.
Parameters	source - the source to generate the JSON string for. If this is provided as a string, it is passed to hs.doc.builder.genComments and the result is used. If it is a table, then it is assumed to have already been generated by a call to hs.doc.builder.genComments.
Returns	string - the JSON string representation of the documentation
Notes	If you have installed the `hs` command line tool (see `hs.ipc`), you can use the following to generate the `docs.json` file that is used to provide documentation for Hammerspoon Spoon bundles: `hs -c "hs.doc.builder.genJSON(\"$(pwd)\")" > docs.json` You can also use this to generate documentation for any third-party-modules you build, but you will have to register the documentation with `hs.doc.registerJSONFile` yourself -- it is not automatically loaded for you like it is for Spoons.
Examples	None
Source	extensions/doc/doc_builder.lua line 194

# genSQL


Signature	`hs.doc.builder.genSQL(source) -> string`
Type	Function
Description	Generates the SQL commands required for creating the search index when creating a docset of the documentation.
Parameters	source - the source to generate the SQL commands for. If this is provided as a string, it is passed to hs.doc.builder.genComments and the result is used. If it is a table, then it is assumed to have already been generated by a call to hs.doc.builder.genComments.
Returns	string - the relevant SQL commands as a string
Notes	None
Examples	None
Source	extensions/doc/doc_builder.lua line 170