[Python-Dev] Similarity of docstrings and decorators

[Andrew Durdin]

It recently struck me that both decorators and docstrings are
syntactic sugar for code that would otherwise follow the function
definition, vide:

@staticmethod
def foo():
    """Frobs the baz"""
    pass

versus

def foo():
    pass
foo.__doc__ = """Frobs the baz"""
foo = staticmethod(foo)

This suggests two things to me: firstly, that the proposed decorator
syntaxes which place the decorators after the def, beside the
docstring, are the most consistent with existing syntax (that for
docstrings); and secondly, that this suggests that it might be better
to have an explicit function "header" section where both decorators
and docstrings will reside. For a conceptual example (not a syntax
proposal):

def foo():
    header:
        staticmethod
        """Frobs the baz"""

    pass

I realise there would be some issues with this--backward compatibility
with existing docstrings (which could probably be resolved by a
gradual deprecation), and Guido's concern about having to "peek inside
the block"--but I thought it worth mentioning this generalised
conception of both features, that highlights their similarity.

(As for peeking inside the function, if a separate header area existed
for the "important
external properties", then it, together with the signature (which is
arguably the most important part of a function definition) would
comprise all that you would need to know externally.)