__doc__ for functions, classes, objects etc.

[Andreas Rossberg]

On 5 September 2011 16:12, Dmitry Soshnikov <dmitry.soshnikov at gmail.com>
 wrote:

> **
> On 05.09.2011 13:26, Andreas Rossberg wrote:
>
> I am indifferent about the general idea of a doc interface,
>
>
> Then I don't think incorrect judging about the concept of an "abstraction"
> is a good topic in this thread (you may open a new one). Abstraction is
> about _abstraction_, it's not about "security". Especially in the
> interpreted dynamically typed language with embedded reflection.
> Abstractions are for programmers. Not for "hackers".
>

Well, properly maintaining language-level abstractions is a prerequisite for
security, but security is by no means the only reason to want abstraction.
Reliability and modularity are others (and the ones that I personally care
about even more). In any case, I don't think you want to introduce or bless
another feature that interferes badly with either of these concerns -- it's
almost guaranteed to lead to legacy that will cause a big headache later.


> but: having to peek at the _implementation_ of something (which is what
> toString does) in order to gather its _interface_ description sounds like a
> fundamental violation of basic principles and exactly the wrong way to go
> about it.
>
>
> Fundamental principle of an abstraction, once again, is _the abstraction_.
> That is, to provide convenient black box with API hiding implementation
> details.
>

I was specifically referring to the separation of interface and
implementation. Documentation is interface description, intended to avoid
having to look at the implementation. Wouldn't it be ironic if the mandatory
way to get to it was by looking at the implementation?

/Andreas
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/es-discuss/attachments/20110905/f0a71fe4/attachment.html>