> 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. -- You received this message because you are subscribed to the Google Groups "Clojure" group. To post to this group, send email to clojure@googlegroups.com Note that posts from new members are moderated - please be patient with your first post. To unsubscribe from this group, send email to clojure+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/clojure?hl=en
