Fork me on GitHub
#cljdoc
<
2023-08-16
>
olttwa14:08:09

In Cljdoc, API Wikilinks seem to be randomly failing when using alias instead of fully-qualified namespaces. For instance, in https://cljdoc.org/d/com.nilenso/goose/0.3.2/api/goose.client#keys, [[d/default-queue]] is broken whereas [[retry/default-opts]] was linked accurately. Please find reference to https://github.com/nilenso/goose/blob/0fecb553457e3f7b1655a1eca63b2491166aaeec/src/goose/client.clj#L21. > Is this a bug or is there a nuance that I'm missing?

lread14:08:43

Hi @U03HVBGMRJ5! Cljdoc wikilinks do not recognize namespace aliases. Here are relevant docs: https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#use-api-wikilinks-from-docstrings. The [[retry/default-ops]] works because it is recognized as a relative wikilink. Personally, I find the relative syntax confusing and just fully qualify my wikilinks.

olttwa05:08:09

Thanks @UE21H2HHD for the prompt response. > Note that if you want to link to vars outside the current namespace you need to either fully qualify those vars or specify them relative to the current namespace This line wasn't clear to me before, but is now after your explanation. Maybe we can explicitly say that users shouldn't reference namespaces via aliases.

lread12:08:23

Yes, good idea, if you were confused, others will be too. I'll make a small update to the docs there.

gratitude-thank-you 2
olttwa05:08:37

The new guidelines are very clear. Thanks for the quick update

👍 2