Le jeudi 12 juin 2014 à 09:32 -0400, Stefan Karpinski a écrit : > In general, there should be a single doc string for a generic > function. It explains the concept and meaning of the function with > variations on usage. The major difference between Python/Matlab and > Julia in terms of doc strings is that there isn't a single place where > the function is defined; there isn't always a single "most generic" > method of a function. That's why having the docstring inside one > particular method seems wrong to me. Having it precede a series of > method definitions of the same generic function – and grouping them is > typical – makes the most sense. Unlike Matlab and Python, when you're > moving a function, you'll typically move all of it's methods anyway, > so the cut-and-paste argument seems pretty moot.
I think we need both a generic documentation, and optional method-specific documentation about possible variations. In some cases you need different docs for each different method, because they act very differently, and you cannot know in advance what a package will exactly do in this function. The best example is plot(), which would give a variety of results depending on what's the object you pass to it. So in that case just showing all docs for each method is the best solution -- with maybe a short generic doc saying "this function plots various things depending on what you pass to it". In other cases the behavior of the method is almost the same for all objects, so the central place is the generic doc. Examples are length(), sort(), and many other standard functions. In some cases, method-specific docs would need to add a short precision, for example when a DataArray is passed instead of an Array, what happens to missing values; or what does length() mean for UTF8Strings. At the moment the help mixes generic function behavior and method-specific variations, which is confusing and does not scale well when packages are added into the mix. Regards
