[Jython-checkins] jython: PySequence Javadoc improvements (no code change)

[frank.wierzbicki]

http://hg.python.org/jython/rev/b7e75bbb30d7
changeset:   6448:b7e75bbb30d7
user:        Jeff Allen <ja...py at farowl.co.uk>
date:        Sun Mar 18 07:09:54 2012 +0000
summary:
  PySequence Javadoc improvements (no code change)

files:
  src/org/python/core/PySequence.java |  44 ++++++++++++++--
  1 files changed, 38 insertions(+), 6 deletions(-)


diff --git a/src/org/python/core/PySequence.java b/src/org/python/core/PySequence.java
--- a/src/org/python/core/PySequence.java
+++ b/src/org/python/core/PySequence.java
@@ -20,6 +20,11 @@
 
     // These methods must be defined for any sequence
     /**
+     * Returns the element of the sequence at the given index. This is an extension point called by
+     * PySequence in its implementation of {@link #__getitem__} It is guaranteed by PySequence that
+     * when it calls <code>pyget(int)</code> the index is within the bounds of the array. Any other
+     * clients must make the same guarantee.
+     * 
      * @param index index of element to return.
      * @return the element at the given position in the list.
      */
@@ -36,7 +41,8 @@
     protected abstract PyObject getslice(int start, int stop, int step);
 
     /**
-     * Repeats the given sequence.
+     * Returns a (concrete subclass of) PySequence that repeats the given sequence, as
+     * in the implementation of <code>__mul__</code> for strings.
      *
      * @param count the number of times to repeat the sequence.
      * @return this sequence repeated count times.
@@ -45,8 +51,11 @@
 
     // These methods only apply to mutable sequences
     /**
-     * Sets the given element of the sequence.
-     *
+     * Sets the indexed element of the sequence to the given value. This is an extension point
+     * called by PySequence in its implementation of {@link #__setitem__} It is guaranteed by
+     * PySequence that when it calls pyset(int) the index is within the bounds of the array. Any
+     * other clients must make the same guarantee.
+     * 
      * @param index index of the element to set.
      * @param value the value to set this element to.
      */
@@ -55,22 +64,45 @@
     }
 
     /**
-     * Sets the given range of elements.
+     * Sets the given range of elements according to Python slice assignment semantics.
+     * If the step size is one, it is a simple slice and the operation is equivalent to
+     * deleting that slice, then inserting the value at that position, regarding the
+     * value as a sequence (if possible) or as a single element if it is not a sequence.
+     * If the step size is not one, but <code>start==stop</code>, it is equivalent to insertion
+     * at that point.
+     * If the step size is not one, and <code>start!=stop</code>, the slice defines a certain number
+     * of elements to be replaced, and the value must be a sequence of exactly that many
+     * elements (or convertible to such a sequence).
+     * 
+     * @param start the position of the first element.
+     * @param stop one more than the position of the last element.
+     * @param step the step size.
+     * @param value an object consistent with the slice assignment
      */
     protected void setslice(int start, int stop, int step, PyObject value) {
         throw Py.TypeError(String.format("'%s' object does not support item assignment",
                                          getType().fastGetName()));
     }
 
-    protected void del(int i) {
+    /**
+     * Deletes an element from the sequence (and closes up the gap).
+     * 
+     * @param index index of the element to delete.
+     */
+    protected void del(int index) {
         throw Py.TypeError(String.format("'%s' object does not support item deletion",
                                          getType().fastGetName()));
     }
 
+    /**
+     * Deletes a contiguous sub-sequence (and closes up the gap).
+     * 
+     * @param start the position of the first element.
+     * @param stop one more than the position of the last element.
+     */
     protected void delRange(int start, int stop) {
         throw Py.TypeError(String.format("'%s' object does not support item deletion",
                                          getType().fastGetName()));
-
     }
 
     @Override

-- 
Repository URL: http://hg.python.org/jython