Properly document LuaSkin with examples

[asmagill]

• Document Objective-C API

  • What's the current process, as we do have this at https://www.hammerspoon.org/docs/LuaSkin/, so what mechanism?
  • May be acceptable, but at least a few of the NS_OPTIONS are currently not defined

• Document Lua side helpers (ls)

• Examples

  • Usage in module development for Hammerspoon
  • NSObject helper functions
  • Using LS_WithObjectWrapper
  • Others?

[asmagill]

@latenitefilms moved the discussion here.

@cmsj how is this built? It looks like at least some of the issues I've had with AppleDoc don't plague the site at https://www.hammerspoon.org/docs/LuaSkin/, but I haven't done a thorough review yet.

The Examples section is sort of a check list for some docs I hope to work on when I take a couple of weeks to visit my daughter next month (she's in the UK and I'm not, so I expect to be self-quarantining in house, assuming restrictions don't change, for a while when I get there and figure that's as good a time as any to catch up on my writing). Most likely they'll end up in the Wiki, unless there is an easy way to merge them with the API docs?

And for the Lua side helpers, I am also planning to add the following:

• ls.deprecated(module, name, message)

  • Used to indicate a function in a module has been deprecated and removed. Message may describe an alternative.
  • Prints message to the console when you try to execute module.name and raises an error.

• ls.deprecationWarning(module, name, message, function)

  • Used to indicate a function has been deprecated, but is still allowed for now.
  • Prints message on first use for this loading of Hammerspoon and then invokes specified function

Maybe others, will update as necessary.

edit - need to preview before posting lists!

[cmsj]

@asmagill check out the build/html/LuaSkin target in the top level Makefile - it uses headerdoc2html which I think comes with Xcode