I wanted to revisit the problem of documenting PTL modules (we had
discussed this on the list, some time ago). Docstrings do not work in
PTL because literal strings are collected as part of the output of a PTL
method.

Maybe no one else is terribly worried about this; but personally I find
that, as my current project grows in size, I miss being able to document
my PTL definitions in the same way I document standard Python
definitions. Down the road this tendency not to document will lead to
unnecessary difficulties, since I hope that others will want to read and
modify the code...

Ideally, a solution for PTL should be as close to Python syntax as
possible, so that PTL docstrings would be recognizable by a Quixote
novice. It should also be correctly interpreted as a docstring so that,
for example, a call to help(my_ptl_module) would return expected results.

Compatibility with documentation tools such as epydoc would also be
beneficial. (Since many of these tools compile the module in order to
discover its docstrings, the syntax could actually differ quite widely
from Python's, as long as ptl_compile can set the __doc__ attribute as
expected.)

I'd like to throw out some possible syntaxes for discussion. I think
some of these were discussed earlier on the list...


----------------------------------------------------------------------
----------------------------------------------------------------------

def doc_attr [html] (request):
     __doc__ = '''
        Syntatically correct Python, just need to bind __doc__
         to the function.
     '''

def doc_pseudo_function [html] (request):
     ___doc___('''
         Syntatically correct, maybe harder to read than the former.
     ''')

def d_modifier [html] (request):
     d"""
     Incorrect Python, though Python-like;
     the 'd' modifier identifies the docstring.
     """

def backticks [html] (request):
     ```
     Correct Python (sort of), and easy to read.
     I wish python-mode would recognize it, though...
     But it risks invoking eval() on a docstring if it is coppied
     into a normal Python function...
     ```

def first_comments [html] (request):
     # Convert the first set of comment lines in the function
     # to a docstring. Reads like documentation anyway...

     # the first empty or non-comment line signifies end-of-doc.
     # I'm pretty sure thats recognizable by the parser...
     ...

"""
A Javadoc style;
stick the docstring above the function.
"""
def javadoc_style [html] (request):
     ....


# A Javadoc-like style,
# using leading comments.
def pseudo_javadoc_comments [html] (request):
     ....

----------------------------------------------------------------------
----------------------------------------------------------------------

I'm sure other syntaxes are possible. If we could settle on a favourite
style, I'll do my best to implement the required changes to ptl_compile.

Again: the goal is not simply to find something readable, but to
implment a change to PTL compliation so that __doc__ attributes are
correctly set on PTL definitions. (The secondary goal is to get Quixote
users documenting their PTL code now, so that the generations to follow
will have a better chance to understand what we've been writing!)

Thoughts?

-- Graham