discussion on examples as metadata

[behrica]

More a discussion, then an issue.

I liked a lot the idea of inline examples as defn metadata.

But I can see that I enter quickly in dependency cycles.
The "examples" I would like to attach to my functions, are not simply testing a function in isolation,
but "combine" various functions across metamorph.ml

Firstly we could of course argue, that these are not pure "examples of one fn", which is correct.

I could as well always workaround, by using the add-example including using a different namespace

@genmeblog
Probably you have experienced this as well before.

[genmeblog]

Generally the main purpose of this library is to enhance documentation with kind of unit docs. Just to show function call and the result without bigger context.
The longer, richer workflows is not a goal. For that we have Clay or other notebook solutions.

I don't see an easy solution without deeper redesign of the library to achieve this. We can of course discuss a little bit more about possible approaches...

[behrica]

I agree, it is for "simple" unit tests.
I helped my self wit a "separated" example file, which does not have this problem.

The "codox" user facing site look the same in both cases, so from a "documenting" point of view we are fine.

[behrica]

I maybe look for a way to "have code in codox" without any need of a notebook...
I see some use to have an "pseudo name space" which is only examples":

Currently I need "hook" my example onto a Var / fn, which I would avoid, if possible.

And I do not look for any way of "writing text"... just the example description is enough.