jython-users

[Jython-users] Python Documentation suggestion...

[<da...@br...>]

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 th=
e
jython.org page near the bottom. In that chapter, Bruce points out that t=
he
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=92t extracted. Although many of the classes are n=
ot
necessary in order to program with Jython, many are and so it=92s valuabl=
e to
run Javadoc in order to generate the HTML documentation.

Here is the makefile that I used to create the Java documentation:

all:
  javadoc -sourcepath C:\Progtools\Jython\ \
  -d C:\ProgTools\Jython\docs\new \
  org.python.core org.python.modules \
  org.python.util org.python.rmi

You=92ll have to adjust the paths to fit your own installation. The sourc=
epath
is where you installed Jython, and =96d indicates the destination directo=
ry
for the generated HTML files. Look up the JDK online documentation for
Javadoc for further details.

Once you generate the documentation, you can poke through and pick up a f=
ew
bits and pieces you wouldn=92t otherwise find.

</TI Patterns text>

I assume this works from the command line as well in Unix and Windows.

I am about to try this myself (after I finish a few weekend tasks) so I
cannot say for certain it works, but Bruce has proved to be very reliable.

BTW, I recommend you read the whole chapter--Bruce is an excellent
instructor--he makes the arcane seem simple. I learned more on one exampl=
e
in that chapter than I did with the whole of the jython examples and FAQ.=
 I
also recommend his Thinking in Java and Thinking in C++ as well.

-- Daniel Lord

-----Original Message-----
From: jyt...@li...
[mailto:jyt...@li...]On Behalf Of
jyt...@li...
Sent: Sunday, February 18, 2001 12:02 PM
To: jyt...@li...
Subject: Jython-users digest, Vol 1 #71 - 1 msg


Send Jython-users mailing list submissions to
	jyt...@li...

To subscribe or unsubscribe via the World Wide Web, visit
	http://lists.sourceforge.net/lists/listinfo/jython-users
or, via email, send a message with subject or body 'help' to
	jyt...@li...

You can reach the person managing the list at
	jyt...@li...

When replying, please edit your Subject line so it is more specific
than "Re: Contents of Jython-users digest..."


Today's Topics:

   1. PythonInterpreter Documentation (Robert Welch)

--__--__--

Message: 1
Date: Sun, 18 Feb 2001 07:53:55 -0500
From: Robert Welch <rob...@ho...>
Organization: @Home Network
To: Jython <Jyt...@li...>
Subject: [Jython-users] PythonInterpreter Documentation

Folks:

Can someone point me to some web documentation for the
PythonInterpreter Java class?  I've wound up at:

http://www.jython.org/docs/api/org.python.util.PythonInterpreter.html

and there's some stuff there, but the Contents, Package & Help
links all seem to be broken.  This means I can't find any info
on the "core" classes, such as org.python.core.PyObject.

Thanks,

	---Rob Welch



--__--__--

_______________________________________________
Jython-users mailing list
Jyt...@li...
http://lists.sourceforge.net/lists/listinfo/jython-users


End of Jython-users Digest

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.