Fix broken cljdoc api analysis

[lread]

Problem

The MrAnderson readme has a cljdoc badge which is showing "API import failed":

I assume that we'd like to fix this.

Diagnosis

Cljdoc is barfing when trying to load mranderson.util namespace. It references leiningen.core.main which is not on the classpath during cljdoc analysis.

Public API

Cljdoc API docs ideally document the public API of a library.

I don't know what the public API of mranderson is, but once I do, we can tell cljdoc to ignore mranderson internals via :no-doc metadata on mranderson namespaces and vars that are considered internal.

This might well be enough to fix cljdoc API analysis. If not we can explore further.

My current guess a public supported nses:

• mranderson.core
• mrnaderson.plugin

Next Steps

I am happy to follow up with a PR once we agree on an approach.

[lread]

Perhaps related?: #34 and #42

[benedekfazekas]

I thing mranderson.core and mranderson.plugin is a good guess. I might consider adding mranderson.move as well which is the real gist what mranderson does (based on Stuart Sierra's work) and could be used independently as well I think. Hope this makes sense.

[lread]

Cool yeah, that seems good. Once I get the cljdoc analysis working I'll share the API that it documents for your review.

[benedekfazekas]

sounds awesome, thanks

[lread]

Ok, @benedekfazekas, I have a cljdoc preview from my dev box for you:

For some reason, aether is not getting :mranderson/inlined metadata and is therefore included when it should not be. I'll take a peek and raise a separate issue.

Otherwise, we are getting to the nitty gritty of what vars to include for each ns. Any var you include would be part of your public API and therefore supported moving forward (barring any deliberate breaking changes). The ones that seemed very likely to me, I marked in green. For the others, I can make guesses, but easier to ask you.

I did a grep.app to learn what folks are using in the wild. I only see iced-nrepl using MrAnderson directly. It uses mranderson.core/copy-source-files and mranderson.core/mranderson.

Grep.app did not find lein-isolate, which uses mranderson.middleware and leiningen.inline-deps, but I expect leiningen.inline-deps won't be part of your public API, right?

Anyhoo, looking forward to learning your thoughts.

[benedekfazekas]

I guess mranderson.core/mranderson mranderson.move are the real candidates. maybe adding a CLI and properly carve away the lein plugin would clarify this a bit more...

[lread]

Cool, I propose starting ultra-conservative and only exposing mranderson.core/mranderson.

You can always add things to the supported API at a later date.

That said you have documented the move ns clearly with ALPHA. So you've given a clear warning. If you were to expose mranderson.move, would it just be move-ns fn to start with?