Feature request: Ability to hide things from the documentation

[Mange]

I have some functions defined in my files that end up in the HTML documentation, despite them being internal and not part of any "public" API. I'd love to be able to hide them from the documentation output to not confuse any users.

Suggestions:

-- LuaCATS supports a @private annotation for class functions.
-- Reusing that syntax at top-level doesn't cause an error in Lua LSP, and is succint.
--- @private
function __sort() end

-- We could also go for our own structure that is not included in LuaCATS.
--- @visibility private
function __compare() end

-- …or
--- @luadox:hide
function __mine() end

[jtackaberry]

Currently I do this by avoiding use of 3 dashes (---) for docs of internal functions, but with LuaCATS I understand why this strategy won't work.

[Mange]

Good workaround with avoiding --- until then. :-)

I think one thing we should consider for this feature is that sometimes you want to document private items, and other times you do not. As an example, if documenting for internal developers in order to help working in a codebase, then private items could still be useful to include (although it should be marked as such), but if the documentation is meant to be shared externally for users of a library, then the items probably should not be included.

So perhaps seeing @private / @visibility as a separate thing from actually "hiding" the item is better. It could also be handled through a config setting.

Prior art:

• Rust:
  • Opt-in; cargo doc --document-private-items will include private items that would otherwise not be included.
  • Documentation picks up visibility from language keywords.
• Ruby YARD:
  • Opt-in; yardoc --private
  • Also supports a specific @private tag (that is different from visibility because of how Ruby works). --no-private will then filter out those items completely instead of showing them with their real visibility and a "Part of a private API, please do not use." warning.
• Javascript JSDoc:
  • Opt-in. --private will show private items in the output.