[Jython-checkins] jython: Javadoc and comment tweaks (mostly Buffer API)
jeff.allen
jython-checkins at python.org
Tue Feb 12 16:29:21 CET 2013
http://hg.python.org/jython/rev/1da2e1095c31
changeset: 7048:1da2e1095c31
user: Jeff Allen <ja...py at farowl.co.uk>
date: Tue Feb 12 11:09:49 2013 +0000
summary:
Javadoc and comment tweaks (mostly Buffer API)
No code change.
files:
src/org/python/core/PyBUF.java | 52 +++++-----
src/org/python/core/PyBuffer.java | 43 +++----
src/org/python/core/buffer/BaseBuffer.java | 9 +-
src/org/python/core/buffer/SimpleBuffer.java | 2 +
src/org/python/core/buffer/Strided1DBuffer.java | 25 +++-
src/org/python/core/buffer/Strided1DWritableBuffer.java | 2 +-
src/org/python/modules/SHA224Digest.java | 12 +-
7 files changed, 77 insertions(+), 68 deletions(-)
diff --git a/src/org/python/core/PyBUF.java b/src/org/python/core/PyBUF.java
--- a/src/org/python/core/PyBUF.java
+++ b/src/org/python/core/PyBUF.java
@@ -3,20 +3,20 @@
/**
* This interface provides a base for the key interface of the buffer API, {@link PyBuffer},
* including symbolic constants used by the consumer of a <code>PyBuffer</code> to specify its
- * requirements and assumptions. The Jython buffer API emulates the CPython buffer API.
+ * requirements and assumptions. The Jython buffer API emulates the CPython buffer API. There are
+ * two reasons for separating parts of <code>PyBuffer</code> into this interface:
* <ul>
- * <li>There are two reasons for separating parts of <code>PyBuffer</code> into this interface: The
- * constants defined in CPython have the names <code>PyBUF_SIMPLE</code>,
+ * <li>The constants defined in CPython have the names <code>PyBUF_SIMPLE</code>,
* <code>PyBUF_WRITABLE</code>, etc., and the trick of defining ours here means we can write
- * {@link PyBUF#SIMPLE}, {@link PyBUF#WRITABLE}, etc. so source code looks similar.</li>
+ * <code>PyBUF.SIMPLE</code>, <code>PyBUF.WRITABLE</code>, etc. so source code looks similar.</li>
* <li>It is not so easy in Java as it is in C to treat a <code>byte</code> array as storing
* anything other than <code>byte</code>, and we prepare for the possibility of buffers with a
* series of different primitive types by defining here those methods that would be in common
- * between <code>(Byte)Buffer</code> and an assumed future <code>FloatBuffer</code> or
+ * between (Byte)<code>Buffer</code> and an assumed future <code>FloatBuffer</code> or
* <code>TypedBuffer<T></code>. (Compare <code>java.nio.Buffer</code>.)</li>
* </ul>
- * Except for other interfaces, it is unlikely any classes would implement <code>PyBUF</code>
- * directly. Users of the Jython buffer API can mostly overlook the distinction and just use
+ * It is unlikely any classes would implement <code>PyBUF</code>, except indirectly through other
+ * interfaces. Users of the Jython buffer API can mostly overlook the distinction and just use
* <code>PyBuffer</code>.
*/
public interface PyBUF {
@@ -39,12 +39,12 @@
/**
* An array reporting the size of the buffer, considered as a multidimensional array, in each
- * dimension and (by its length) number of dimensions. The size is the size in "items". An item
- * is the amount of buffer content addressed by one index or set of indices. In the simplest
- * case an item is a single unit (byte), and there is one dimension. In complex cases, the array
- * is multi-dimensional, and the item at each location is multi-unit (multi-byte). The consumer
- * must not modify this array. A valid <code>shape</code> array is always returned (difference
- * from CPython).
+ * dimension and (by its length) giving the number of dimensions. The size of the buffer is its
+ * size in "items". An item is the amount of buffer content addressed by one index or set of
+ * indices. In the simplest case an item is a single unit (byte), and there is one dimension. In
+ * complex cases, the array is multi-dimensional, and the item at each location is multi-unit
+ * (multi-byte). The consumer must not modify this array. A valid <code>shape</code> array is
+ * always returned (difference from CPython).
*
* @return the dimensions of the buffer as an array
*/
@@ -59,7 +59,7 @@
/**
* The total number of units (bytes) stored, which will be the product of the elements of the
- * <code>shape</code> array, and the item size.
+ * <code>shape</code> array, and the item size in units.
*
* @return the total number of units stored.
*/
@@ -81,13 +81,13 @@
/**
* The <code>suboffsets</code> array is a further part of the support for interpreting the
* buffer as an n-dimensional array of items, where the array potentially uses indirect
- * addressing (like a real Java array of arrays, in fact). This is only applicable when there
- * are more than 1 dimension and works in conjunction with the <code>strides</code> array. (More
+ * addressing (like a real Java array of arrays, in fact). This is only applicable when there is
+ * more than 1 dimension, and it works in conjunction with the <code>strides</code> array. (More
* on this in the CPython documentation.) When used, <code>suboffsets[k]</code> is an integer
- * index, bit a byte offset as in CPython. The consumer must not modify this array. When not
+ * index, not a byte offset as in CPython. The consumer must not modify this array. When not
* needed for navigation <code>null</code> is returned (as in CPython).
*
- * @return suboffsets array or null in not necessary for navigation
+ * @return suboffsets array or <code>null</code> if not necessary for navigation
*/
int[] getSuboffsets();
@@ -108,15 +108,15 @@
static final int MAX_NDIM = 64;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
- * specify that it expects to write to the buffer contents. getBuffer will raise an exception if
- * the exporter's buffer cannot meet this requirement.
+ * specify that it expects to write to the buffer contents. <code>getBuffer</code> will raise an
+ * exception if the exporter's buffer cannot meet this requirement.
*/
static final int WRITABLE = 0x0001;
/**
* A constant used by the consumer in its call to {@link BufferProtocol#getBuffer(int)} to
* specify that it assumes a simple one-dimensional organisation of the exported storage with
- * item size of one. getBuffer will raise an exception if the consumer sets this flag and the
- * exporter's buffer cannot be navigated that simply.
+ * item size of one. <code>getBuffer</code> will raise an exception if the consumer sets this
+ * flag and the exporter's buffer cannot be navigated that simply.
*/
static final int SIMPLE = 0;
/**
@@ -162,7 +162,7 @@
* specify that it will assume a contiguous organisation of the units, but will enquire which
* organisation it actually is.
*
- * getBuffer will raise an exception if the exporter's buffer is not contiguous.
+ * <code>getBuffer</code> will raise an exception if the exporter's buffer is not contiguous.
* <code>ANY_CONTIGUOUS</code> implies <code>STRIDES</code>.
*/
// Further CPython strangeness since it uses the strides array to answer the enquiry.
@@ -216,7 +216,7 @@
/* Constants for readability, not standard for CPython */
/**
- * Field mask, use as in <code>if ((flags&NAVIGATION) == STRIDES) ...</code>. The importance of
+ * Field mask, used as in <code>if ((flags&NAVIGATION) == STRIDES) ...</code>. The importance of
* the subset of flags defined by this mask is not so much in their "navigational" character as
* in the way they are treated in a buffer request.
* <p>
@@ -243,7 +243,7 @@
*/
static final int IS_F_CONTIGUOUS = F_CONTIGUOUS & ~STRIDES;
/**
- * Field mask, use as in <code>if ((flags&CONTIGUITY)== ... ) ...</code>.
+ * Field mask, used as in <code>if ((flags&CONTIGUITY)== ... ) ...</code>.
*/
static final int CONTIGUITY = (C_CONTIGUOUS | F_CONTIGUOUS | ANY_CONTIGUOUS) & ~STRIDES;
-}
\ No newline at end of file
+}
diff --git a/src/org/python/core/PyBuffer.java b/src/org/python/core/PyBuffer.java
--- a/src/org/python/core/PyBuffer.java
+++ b/src/org/python/core/PyBuffer.java
@@ -163,9 +163,9 @@
* When a <code>PyBuffer</code> is the target, the same checks are carried out on the consumer
* flags, and a return will normally be a reference to that buffer. A Jython
* <code>PyBuffer</code> keeps count of these re-exports in order to match them with the number
- * of calls to {@link #release()}. When the last matching release() arrives it is considered
- * "final", and release actions may then take place on the exporting object. After the final
- * release of a buffer, a call to <code>getBuffer</code> should raise an exception.
+ * of calls to {@link #release()}. When the last matching <code>release()</code> arrives it is
+ * considered "final", and release actions may then take place on the exporting object. After
+ * the final release of a buffer, a call to <code>getBuffer</code> should raise an exception.
*/
@Override
PyBuffer getBuffer(int flags) throws PyException;
@@ -213,16 +213,17 @@
* <code>this.getPointer(i)</code>. A request for a slice where <code>start</code> <i>= s</i>,
* <code>length</code> <i>= N</i> and <code>stride</code> <i>= m</i>, results in a buffer
* <i>y</i> such that <i>y(k) = x(s+km)</i> where <i>k=0..(N-1)</i>. In Python terms, this is
- * the slice <i>x[s : s+(N-1)m+1 : m]</i> (if m>0) or the slice <i>x[s : s+(N-1)m-1 : m]</i>
- * (if m<0). Implementations should check that this range is entirely within the current
- * buffer.
+ * the slice <i>x[s : s+(N-1)m+1 : m]</i> (if <i>m>0</i>) or the slice <i>x[s : s+(N-1)m-1 :
+ * m]</i> (if <i>m<0</i>). Implementations should check that this range is entirely within
+ * the current buffer.
* <p>
* In a simple buffer backed by a contiguous byte array, the result is a strided PyBuffer on the
* same storage but where the offset is adjusted by <i>s</i> and the stride is as supplied. If
* the current buffer is already strided and/or has an item size larger than single bytes, the
- * new start index, length and stride will be translated from the arguments given, through this
- * buffer's stride and item size. The consumer always expresses <code>start</code> and
- * <code>strides</code> in terms of the abstract view of this buffer.
+ * new <code>start</code> index, <code>length</code> and <code>stride</code> will be translated
+ * from the arguments given, through this buffer's stride and item size. The caller always
+ * expresses <code>start</code> and <code>strides</code> in terms of the abstract view of this
+ * buffer.
*
* @param flags specifying features demanded and the navigational capabilities of the consumer
* @param start index in the current buffer
@@ -265,13 +266,11 @@
* Return a structure describing the slice of a byte array that holds the data being exported to
* the consumer. For a one-dimensional contiguous buffer, assuming the following client code
* where <code>obj</code> has type <code>BufferProtocol</code>:
- *
* <pre>
* PyBuffer a = obj.getBuffer();
* int itemsize = a.getItemsize();
* PyBuffer.Pointer b = a.getBuf();
* </pre>
- *
* the item with index <code>k</code> is in the array <code>b.storage</code> at index
* <code>[b.offset + k*itemsize]</code> to <code>[b.offset + (k+1)*itemsize - 1]</code>
* inclusive. And if <code>itemsize==1</code>, the item is simply the byte
@@ -287,17 +286,15 @@
PyBuffer.Pointer getBuf();
/**
- * Return a structure describing the slice of a byte array that points to a single item from the
- * data being exported to the consumer. For a one-dimensional contiguous buffer, assuming the
+ * Return a structure describing the position in a byte array of a single item from the data
+ * being exported to the consumer. For a one-dimensional contiguous buffer, assuming the
* following client code where <code>obj</code> has type <code>BufferProtocol</code>:
- *
* <pre>
* int k = ... ;
* PyBuffer a = obj.getBuffer();
* int itemsize = a.getItemsize();
* PyBuffer.Pointer b = a.getPointer(k);
* </pre>
- *
* the item with index <code>k</code> is in the array <code>b.storage</code> at index
* <code>[b.offset]</code> to <code>[b.offset + itemsize - 1]</code> inclusive. And if
* <code>itemsize==1</code>, the item is simply the byte <code>b.storage[b.offset]</code>
@@ -312,11 +309,10 @@
PyBuffer.Pointer getPointer(int index);
/**
- * Return a structure describing the slice of a byte array that points to a single item from the
- * data being exported to the consumer, in the case that array may be multi-dimensional. For a
+ * Return a structure describing the position in a byte array of a single item from the data
+ * being exported to the consumer, in the case that array may be multi-dimensional. For a
* 3-dimensional contiguous buffer, assuming the following client code where <code>obj</code>
* has type <code>BufferProtocol</code>:
- *
* <pre>
* int i, j, k;
* // ... calculation that assigns i, j, k
@@ -324,18 +320,17 @@
* int itemsize = a.getItemsize();
* PyBuffer.Pointer b = a.getPointer(i,j,k);
* </pre>
- *
* the item with index <code>[i,j,k]</code> is in the array <code>b.storage</code> at index
* <code>[b.offset]</code> to <code>[b.offset + itemsize - 1]</code> inclusive. And if
* <code>itemsize==1</code>, the item is simply the byte <code>b.storage[b.offset]</code>
* <p>
* Essentially this is a method for computing the offset of a particular index. The client is
* free to navigate the underlying buffer <code>b.storage</code> without respecting these
- * boundaries.
- * <p>
- * If the buffer is also non-contiguous, <code>b.storage[b.offset]</code> is still the (first
- * byte of) the item at index [0,...,0]. However, it is necessary to navigate <code>b</code>
- * using the shape, strides and sub-offsets provided by the API.
+ * boundaries. If the buffer is non-contiguous, the above description is still valid (since a
+ * multi-byte item must itself be contiguously stored), but in any additional navigation of
+ * <code>b.storage[]</code> to other units, the client must use the shape, strides and
+ * sub-offsets provided by the API. Normally one starts <code>b = a.getBuf()</code> in order to
+ * establish the offset of index [0,...,0].
*
* @param indices multidimensional index at which to position the pointer
* @return structure defining the byte[] slice that is the shared data
diff --git a/src/org/python/core/buffer/BaseBuffer.java b/src/org/python/core/buffer/BaseBuffer.java
--- a/src/org/python/core/buffer/BaseBuffer.java
+++ b/src/org/python/core/buffer/BaseBuffer.java
@@ -22,7 +22,7 @@
* passed to the constructor. Otherwise, all methods for write access raise a
* <code>BufferError</code> read-only exception and {@link #isReadonly()} returns <code>true</code>.
* Sub-classes can follow the same pattern, setting {@link PyBUF#WRITABLE} in the constructor and,
- * if they have to override the operations that write (<code>storeAt</code> and
+ * if they have to, overriding the operations that write (<code>storeAt</code> and
* <code>copyFrom</code>). The recommended pattern is:
*
* <pre>
@@ -31,9 +31,10 @@
* }
* // ... implementation of the write operation
* </pre>
- *
- * The implementors of simple buffers will find it efficient to override the generic access methods
- * to which performance might be sensitive, with a calculation specific to their actual type.
+ * Another approach, used in the standard library, is to have distinct classes for the writable and
+ * read-only variants. The implementors of simple buffers will find it efficient to override the
+ * generic access methods to which performance might be sensitive, with a calculation specific to
+ * their actual type.
* <p>
* At the time of writing, only one-dimensional buffers of item size one are used in the Jython
* core.
diff --git a/src/org/python/core/buffer/SimpleBuffer.java b/src/org/python/core/buffer/SimpleBuffer.java
--- a/src/org/python/core/buffer/SimpleBuffer.java
+++ b/src/org/python/core/buffer/SimpleBuffer.java
@@ -48,6 +48,7 @@
* @throws ArrayIndexOutOfBoundsException if <code>index0</code> and <code>size</code> are
* inconsistent with <code>storage.length</code>
*/
+ // XXX: "for sub-class use" = should be protected?
public SimpleBuffer(byte[] storage, int index0, int size) throws PyException,
ArrayIndexOutOfBoundsException {
this();
@@ -90,6 +91,7 @@
* @param storage the array of bytes storing the implementation of the exporting object
* @throws NullPointerException if <code>storage</code> is null
*/
+ // XXX: "for sub-class use" = should be protected?
public SimpleBuffer(byte[] storage) throws NullPointerException {
this();
this.storage = storage; // Exported data (index0=0 from initialisation)
diff --git a/src/org/python/core/buffer/Strided1DBuffer.java b/src/org/python/core/buffer/Strided1DBuffer.java
--- a/src/org/python/core/buffer/Strided1DBuffer.java
+++ b/src/org/python/core/buffer/Strided1DBuffer.java
@@ -9,21 +9,24 @@
* properties in the usual way, designating a slice (or all) of a byte array, but also a
* <code>stride</code> property (equal to <code>getStrides()[0]</code>).
* <p>
- * Let this underlying buffer be the byte array <i>u(i)</i> for <i>i=0..N-1</i>, let <i>x</i> be the
+ * Let the underlying buffer be the byte array <i>u(i)</i> for <i>i=0..N-1</i>, let <i>x</i> be the
* <code>Strided1DBuffer</code>, and let the stride be <i>p</i>. The storage works as follows.
* Designate by <i>x(j)</i>, for <i>j=0..L-1</i>, the byte at index <i>j</i>, that is, the byte
- * retrieved by <code>x.byteAt(j)</code>. Then, we store <i>x(j)</i> at <i>u(a+pj)</i>, that is,
- * <i>x(0)</i> is at <i>u(a)</i>. When we construct such a buffer, we have to supply <i>a</i> =
+ * retrieved by <code>x.byteAt(j)</code>. Thus, we store <i>x(j)</i> at <i>u(a+pj)</i>, that is,
+ * <i>x(0) = u(a)</i>. When we construct such a buffer, we have to supply <i>a</i> =
* <code>index0</code>, <i>L</i> = <code>length</code>, and <i>p</i> = <code>stride</code> as the
* constructor arguments. The last item in the slice <i>x(L-1)</i> is stored at <i>u(a+p(L-1))</i>.
- * If <i>p<0</i> and <i>L>1</i>, this will be to the left of <i>u(a)</i>, so the constructor
- * argument index0 is not then the low index of the range occupied by the data. Clearly both these
- * indexes must be in the range 0 to <i>N-1</i> inclusive, a rule enforced by the constructors
+ * For the simple case of positive stride, constructor argument <code>index0</code> is the low index
+ * of the range occupied by the data. When the stride is negative, that is to say <i>p<0</i>, and
+ * <i>L>1</i>, this will be to the left of <i>u(a)</i>, and the constructor argument
+ * <code>index0</code> is not then the low index of the range occupied by the data. Clearly both
+ * these indexes must be in the range 0 to <i>N-1</i> inclusive, a rule enforced by the constructors
* (unless <i>L=0</i>, when it is assumed no array access will take place).
* <p>
* The class may be used by exporters to create a strided slice (e.g. to export the diagonal of a
* matrix) and in particular by other buffers to create strided slices of themselves, such as to
- * create the memoryview that is returned as an extended slice of a memoryview.
+ * create the <code>memoryview</code> that is returned as an extended slice of a
+ * <code>memoryview</code>.
*/
public class Strided1DBuffer extends BaseBuffer {
@@ -60,9 +63,14 @@
/**
* Provide an instance of <code>Strided1DBuffer</code> with navigation variables initialised,
- * for sub-class use. The buffer ( {@link #storage}, {@link #index0}), and the navigation (
+ * for sub-class use. The buffer ({@link #storage}, {@link #index0}), and the navigation (
* {@link #shape} array and {@link #stride}) will be initialised from the arguments (which are
* checked for range).
+ * <p>
+ * The sub-class constructor should check that the intended access is compatible with this
+ * object by calling {@link #checkRequestFlags(int)}. (See the source of
+ * {@link Strided1DWritableBuffer#Strided1DWritableBuffer(int, byte[], int, int, int)}
+ * for an example of this use.)
*
* @param storage raw byte array containing exported data
* @param index0 index into storage of item[0]
@@ -72,6 +80,7 @@
* @throws ArrayIndexOutOfBoundsException if <code>index0</code>, <code>length</code> and
* <code>stride</code> are inconsistent with <code>storage.length</code>
*/
+ // XXX: "for sub-class use" = should be protected?
public Strided1DBuffer(byte[] storage, int index0, int length, int stride)
throws ArrayIndexOutOfBoundsException, NullPointerException {
this();
diff --git a/src/org/python/core/buffer/Strided1DWritableBuffer.java b/src/org/python/core/buffer/Strided1DWritableBuffer.java
--- a/src/org/python/core/buffer/Strided1DWritableBuffer.java
+++ b/src/org/python/core/buffer/Strided1DWritableBuffer.java
@@ -88,7 +88,7 @@
if (length > 0) {
// Translate start relative to underlying buffer
- int compStride= this.stride * stride;
+ int compStride = this.stride * stride;
int compIndex0 = index0 + start * this.stride;
// Construct a view, taking a lock on the root object (this or this.root)
return new SlicedView(getRoot(), flags, storage, compIndex0, length, compStride);
diff --git a/src/org/python/modules/SHA224Digest.java b/src/org/python/modules/SHA224Digest.java
--- a/src/org/python/modules/SHA224Digest.java
+++ b/src/org/python/modules/SHA224Digest.java
@@ -1,6 +1,6 @@
package org.python.modules;
-/**
+/*
* Copyright 2011 Gaurav Raje
* Licensed to PSF under a Contributor Agreement.
*/
@@ -8,13 +8,14 @@
/**
* SHA-224 as described in RFC 3874. This introduces the SHA224 Digest which has
- * been ommitted from the JDK {@link java.security}.
- *
+ * been omitted from the JDK <code>java.security</code>.
*
* This implementation has been borrowed from the Bouncy Castle implementation
- * of SHA2 algorithms. Since they are MIT Licensed, they are compatible with
+ * of SHA2 algorithms.
+ *
+ * Since they are MIT Licensed, they are compatible with
* this project. Their mandatory copyright notice follows.
- *
+ * <pre>
* Copyright (c) 2000 - 2011 The Legion Of The Bouncy Castle
* (http://www.bouncycastle.org)
*
@@ -35,6 +36,7 @@
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
+ * </pre>
*/
public class SHA224Digest
extends MessageDigest
--
Repository URL: http://hg.python.org/jython
More information about the Jython-checkins
mailing list