Re: [Jython-users] Python Documentation suggestion... a little warning

[Samuele P. <pe...@in...>]

A little warning:

[Daniel Lord]
> Bruce Eckels (a Jython-god in training it seems), has a full chapter on
> Jython in his "Thinking Patterns" book -- you can find a link to it on the
> jython.org page near the bottom. In that chapter, Bruce points out that the
> documentation strings are in the code, but no one (ahem! Attention: an
> oversight jython crew?) extracted them with javadoc.
>
> He describes the following method to create jython documentation:
>
> <TI Patterns text>
> Jython 2.0, for some reason, is distributed with only minimal API
> documentation. In fact, only PythonInterpreter has the Java documentation
> created for it. The Java documentation strings are there for the rest of the
> classes, but they weren't extracted. Although many of the classes are not
> necessary in order to program with Jython, many are and so it's valuable to
> run Javadoc in order to generate the HTML documentation.
>
This just my opinion but also - I think - a necessary warning.
It is not a final jython developers statement on this.

Only PythonInterpreter javadoc is extracted because is the only
interface that will be clearly supported and its considered
to be stable or should evolve in a manner to keep things working.
It is clear that other interfaces should reach this status,
and for example that constructing and using basic methods
on Lists or Dictionary from java side should be ok etc
or creating extensions. The FAQ contains some useful
info on this.

We are working on a preexistent codebase - where there are things
that are public and should better be protected or private, and
other that have a poor interface if for external use.

What is really needed is something like CPython
 Extending and Embedding
 Python/C API
manuals that defines what is intended for external use, but this
involves also much decisions and sometime redesign.
So AFIAK don't hold your breath. But contributions
and discussions in this direction are welcome.

On the other hand there is no intention of changing things just for fun
but some changes maybe required to improve jython, fix bugs
or keep up with python development.

I imagine  it is ok to extract doc to learn basic things about
PyObject, PyList and PyDictionary
but then for the moment is up to the user to figure out what will last and what
could possibly
change or is just internal logic  (the FAQ can help for this). And one should
accept that code using undocumented APIs
can be broken by future releases. And sadly and badly the presence of a javadoc
comment
may but does not mean - by now - documented API, sorry.

My advice is to keep the java<->jython code interface as simple as possible on
the java side,
and to do the complicated interface things on jython side, because it is both
easier and more stable.

Given the temporary lack of clean API doc, if one needs to do complicated
things, it is better to post
something and ask on jython-dev, for topics not covered by the FAQ.

regards, Samuele Pedroni.