"M.-A. Lemburg" <mal@lemburg.com> wrote: > > IMHO, David Goodger's (<dgoodger@bigfoot.com>) idea of using a > > __docs__ dictionary is a better solution: > > = > > - It provides all docstrings for the attributes of an object in a > > single place. > > = > > * Handy in interactive mode. > > * This simplifies the generation of documentation considerably. > > = > > - It is easier to explain in the documentation > = > The downside is that it doesn't work well together with > class inheritance: docstrings of the above form can > be overridden or inherited just like any other class > attribute. Yep. That's why David also proposed a `doc' function combining the `__docs__' of a class with all its ancestor's __docs__. > > Normally, Python concatenates adjacent strings. It doesn't do this > > with docstrings. I think Python's behavior would be more consistent > > if docstrings were concatenated like any other strings. > = > Huh ? It does... > = > >>> class C: > ... "first line"\ > ... "second line" > ... = > >>> C.__doc__ > 'first linesecond line' > = > And the same works for the attribute doc strings too. Surprise. I tried it this morning. Didn't use a backslash, though. And al= most = overlooked it now. > > > b =3D 2 > > > > > > def x(self): > > > "C.x doc string" > > > y =3D 3 > > > return 1 > > > > > > "b's doc string" > > > > > > Since the definition of method "x" currently does not reset the= > > > used assignment name variable, it is still valid when the compi= ler > > > reaches the docstring "b's doc string" and thus assigns the str= ing > > > to __doc__b__. > > = > > This is rather surprising behavior. Does this mean that a string in > > the middle of a function definition would be interpreted as the > > docstring of the function? > = > No, since at the beginning of the function the name variable > is set to NULL. Fine. Could the attribute docstrings follow the same pattern, then? > > > A possible solution to this problem would be resetting the name= > > > variable for all non-expression nodes. > > = > > IMHO, David Goodger's proposal of indenting the docstring relative to= the > > attribute it refers to is a better solution. > > = > > If that requires too many changes to the parser, the name variable > > should be reset for all statement nodes. > = > See my other mail: indenting is only allowed for blocks of > code and these are usually started with a colon -- doesn't > work here. Too bad. It's-still-a-great-addition-to-Python ly, = Christian -- = Christian Tanzer tanzer@swing.co.= at Glasauergasse 32 Tel: +43 1 876 62 = 36 A-1130 Vienna, Austria Fax: +43 1 877 66 = 92
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4