Generating documentation for components

[Dominic Monroe]

The choice to use multi-methods has an annoying side-effect: there's no way to inform editors/codox "this keyword corresponds (among other things) to an extension of integrant.core/init-key". I'm opening this issue to discuss ways in which integrant could (or shouldn't) integrate into tools like codox (and cljdoc) and even orchard/cider & family. I do this with the knowledge that you're also the maintainer of codox, so overlapping thoughts can be brought in.

I experimented with some ad-hoc methods of attaching documentation to multi-method implementations, but they unfortunately failed. My approach was attempting to attach metadata to the functions that go into the multimethod registry itself, and then reading the metadata back out later.

The major feature I'd want is for Codox to be able to detect which libraries are adding the multi-method extensions and show a line-item in the HTML. I think it's worth having an eye to making it reasonably easy for editor tooling to extend integration to whatever we come up with also, but I think the use-case is more constrained there.

[James Reeves]

This sounds like a broader problem than Integrant. It encompasses any library that makes use of namespaced keywords, including spec.

There has been some talk around introducing a way of documenting keywords within the context of spec, though as far as I'm aware, nothing has been implemented yet.

Adding detection of multimethod implementations to Codox is certainly possible, though someone would need to write it. The larger problem seem to me to be how to get buy-in from other tools. Ideally, there would be some sort of official improvement to keyword/multimethod documentation.