[LDoc Q] How to combine documentation for a class implemented in multiple files?

["Gary V. Vaughan" <gary@...>]

I'm in the process of converting lua-stdlib Luadoc documentation over to LDoc.

I'm in the process of modularising stdlib, to a much improved self-contained hygienic module per require style.  Unfortunately I broke Luadoc generation, by supporting individual loading of arbitrary modules, that also introduced some dependency cycles -- this only worked previously because a single `require "std"` loaded the modules (into _G!!) in topological order.  I've broken the cycles by taking a few of the heavily shared functions from list.lua, table.lua and tree.lua into a new base.lua, such that rather than list.lua requiring table.lua requiring list.lua etc, both list.lua and table.lua now load the shared functions they need from base.lua, and then reexport them through the table returned to require calls.

Now that I'm converting the docu-comments to LDoc format, I'd like to be able to:

  i) document the functions in base.lua near their definitions in that file;
 ii) have the list method documentation from base.lua show up list.html, table methods in table.html and tree methods in tree.html.

I realise I could split base.lua up into three files with only two or three function each, and use @submodule to add their docs to list.html, table.html and tree.html respectively, but then the methods documented in base.lua are still in a separate section from the methods genuinely documented in list.lua etc. And that is an implementation detail I don't want to annoy the reader with. Not to mention that I'll have to use 3 requires instead of 1 every time I need the functions from base.lua in another module.

I realise I could also move just the docu-comments into the appropriate file, even though the methods themselves have to stay in base.lua to avoid the dependency cycles, but that is just begging for them to go out of sync with each other over time.

Is there a better way?

Cheers,
-- 
Gary V. Vaughan (gary AT vaughan DOT pe)

Attachment: signature.asc
Description: Message signed with OpenPGP using GPGMail