mk-session docstring: document sources

[holyjak]

It wasn't clear from the docstrings that mk-session actually takes rule sources, and in what form. It's better to include the information from http://www.clara-rules.org/docs/ruleforms/ right here.

[EthanEChristian]

Thanks holyjak, the contract on this macro is a bit fiddly and clarification was certainly needed.

[mrrodriguez]

I think this is an improvement to the doc string overall.

I do think it's a bit more strict in the doc string than the actual fn is though.

The concept of a "rule source" is protocol-based. The caller could give other data types that represent rule sources.

There is a clara.rules.compiler/IRuleSource protocol that has a few built-in extensions to it for things like clojure.lang.Symbol as can be seen here. People can extend it to other things, eg. clojure.lang.Var types if they wanted to (I've done this before). If what is given does not satisfy this protocol, then it is assumed to indeed be a sequence of rule/query (aka "production") data structures. This logic can be observed here.

[WilliamParker]

I agree with @mrrodriguez 's comments on IRuleSource implementors being valid alternative arguments and also that this is a net improvement on the documentation. I also agree with renaming "args" to the more descriptive "sources-and-args".

@holyjak if you want to add that here, feel free, but otherwise I'm inclined to merge this soon unless there are objections. I'm happy to follow up with a short note about ISourceRule in the docs afterward. Thanks for pointing out the missing info!