doc strings for both interfaces and concrete implementations

[Warren Lynn]

Is there a way to create doc strings on both interfaces (procotols, multi functions) and concrete implementations (protocol implementation, multi-methods)? For now it seems to me I can only have doc strings for the interfaces. If that is the case, I feel it is something worth fixing, because in my view doc string is not a nice-to-have thing, but essential for dynamic languages.

Assuming we don't have it yet, what I am hoping for is, when I do (doc symbol), or use slime-describe-symbol, it should list the doc strings for the interfaces along with the doc strings of all of its concrete implementations.

For example, I may have a multi-function like this:

(defmulti make-obj
  "Create a new obj."
  (fn [& args] (first args)))

This multi function dispatches on the first argument, and each method can have quite different argument list and of course doc strings. But for now I don't seem to have a way to document them.

Another thing I hope for (but less important), is to be able to have different doc strings for different signatures of the same function.

I think computer language is called "language" for a reason. It is not just for making computers to do magic things, but also be able to let people (youself in 4 months or another programmer) to under how that magic happens. It is a communication media like a natural language, and doc strings are even more important here because dynamic languages are so "dynamic".

[Tassilo Horn]

Warren Lynn <wrn....@gmail.com> writes:

> Is there a way to create doc strings on both interfaces (procotols,
> multi functions) and concrete implementations (protocol
> implementation, multi-methods)?

No, I don't think so.

> Assuming we don't have it yet, what I am hoping for is, when I do (doc
> symbol), or use slime-describe-symbol, it should list the doc strings
> for the interfaces along with the doc strings of all of its concrete
> implementations.

You could use alter-meta! to add a hunk to the docstring of the
"interface" at the place where you add a new implementation (to have
impl and docs near each other). Not all interfacy thingies know their
implementations, btw, so having separate docs for the impls wouldn't
neccessarily allow what you request above.

> Another thing I hope for (but less important), is to be able to have
> different doc strings for different signatures of the same function.

In general, all different versions of a function should somehow do the
same thing, so with separate docstrings you'd need to repeat yourself.
A good guideline is to write the "big picture" first, followed by the
meaning of the different parameters.

Bye,
Tassilo

[Warren Lynn]

In general, all different versions of a function should somehow do the
same thing, so with separate docstrings you'd need to repeat yourself.
A good guideline is to write the "big picture" first, followed by the
meaning of the different parameters.

I agree the design should keep all implementations to do the same thing *conceptually*, as that is what an interface is for. However, I can imagine it is very common that a concrete implementation needs extra documentation for certain implementation specific things. That does not mean the implementation violates the interface, it is just that there are more details that are outside the scope of the interface. An interface spec cannot capture everything, otherwise it is already a concrete implementation instead of an interface. A simple example will be "nth". If "nth" were defined as an interface, then its spec would be "Return the nth element of an ordered collection". But for its implementation of a sequence, the doc can say "this takes linear time", or maybe "will throw an exception on infinite sequence". But for its implementation of a vector, it may say "this takes constant time".

In summary, in my view, this is a very legitimate and basic need.

[Tassilo Horn]

Warren Lynn <wrn....@gmail.com> writes:

>> In general, all different versions of a function should somehow do
>> the same thing, so with separate docstrings you'd need to repeat
>> yourself. A good guideline is to write the "big picture" first,
>> followed by the meaning of the different parameters.
>>
> I agree the design should keep all implementations to do the same
> thing *conceptually*, as that is what an interface is for. However, I
> can imagine it is very common that a concrete implementation needs

> extra documentation for certain implementation specific things. [...]

>
> In summary, in my view, this is a very legitimate and basic need.

I won't object, and the alter-meta! approach allows you to do that. Of
course, it cannot provide documentation for the implementations, but the
interface docs may be extended with impl docs incrementally at the
location where the implementation is defined. That's at least better
than nothing...

Bye,
Tassilo

[Warren Lynn]

I won't object, and the alter-meta! approach allows you to do that.  Of

course, it cannot provide documentation for the implementations, but the
interface docs may be extended with impl docs incrementally at the
location where the implementation is defined.  That's at least better
than nothing...

Bye,
Tassilo

Thanks for pointing out the alternative. As you said, this is better than nothing. I filed a Jira ticket for this and hope some day it will get some consideration.