Improved comments on VDBE opcodes, for better documentation. No code

or logic changes.

FossilOrigin-Name: 2d32e4876e0b162730f81e5c2658be12d64a9a99

manifest

@@ -1,5 +1,5 @@
-C Add\sconstraints\s(enforced\sonly\swhen\sSQLITE_DEBUG\sis\senabled)\son\sthe\suse\sof\nOP_Next\sand\sOP_Prev.
+C Improved\scomments\son\sVDBE\sopcodes,\sfor\sbetter\sdocumentation.\s\sNo\scode\nor\slogic\schanges.
-D 2014-07-25T18:01:06.435
+D 2014-07-25T18:37:42.754
 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f
 F Makefile.in 5eb79e334a5de69c87740edd56af6527dd219308
 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23
@@ -283,7 +283,7 @@ F src/update.c 01564b3c430f6c7b0a35afaf7aba7987206fa3a5
 F src/utf.c a0314e637768a030e6e84a957d0c4f6ba910cc05
 F src/util.c 3076bdd51cdbf60a6e2e57fada745be37133c73e
 F src/vacuum.c 3728d74919d4fb1356f9e9a13e27773db60b7179
-F src/vdbe.c c6a9094a56b3dd4769243051a512f89763af7de5
+F src/vdbe.c b7af861342a215c7f27d3f20d92fe0b70f54fb3e
 F src/vdbe.h c63fad052c9e7388d551e556e119c0bcf6bebdf8
 F src/vdbeInt.h f5513f2b5ac1e2c5128996c7ea23add256a301df
 F src/vdbeapi.c 24e40422382beb774daab11fe9fe9d37e8a04949
@@ -1184,7 +1184,7 @@ F tool/vdbe_profile.tcl 67746953071a9f8f2f668b73fe899074e2c6d8c1
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh 0abfd78ceb09b7f7c27c688c8e3fe93268a13b32
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P 114dcf33670fd98a1ebbac0e44f66b2d8bcccddf
+P 2230c74f1efa591770176c9b40e920724a3c39e1
-R f27032fe9d592a52e4ec63c28d270176
+R 29600123a95daa5177cd67bf8abb597c
 U drh
-Z 96714d48e7c72e5d439e8f51e5a0d88e
+Z 36e2e79e107a063c258f47507608b039

manifest.uuid

@@ -1 +1 @@
-2230c74f1efa591770176c9b40e920724a3c39e1
+2d32e4876e0b162730f81e5c2658be12d64a9a99

src/vdbe.c

@@ -767,12 +767,14 @@ case OP_Return: {           /* in1 */
 
 /* Opcode: InitCoroutine P1 P2 P3 * *
 **
-** Set up register P1 so that it will OP_Yield to the co-routine
+** Set up register P1 so that it will Yield to the coroutine
 ** located at address P3.
 **
-** If P2!=0 then the co-routine implementation immediately follows
+** If P2!=0 then the coroutine implementation immediately follows
-** this opcode.  So jump over the co-routine implementation to
+** this opcode.  So jump over the coroutine implementation to
 ** address P2.
+**
+** See also: EndCoroutine
 */
 case OP_InitCoroutine: {     /* jump */
   assert( pOp->p1>0 &&  pOp->p1<=(p->nMem-p->nCursor) );
@@ -788,9 +790,11 @@ case OP_InitCoroutine: {     /* jump */
 
 /* Opcode:  EndCoroutine P1 * * * *
 **
-** The instruction at the address in register P1 is an OP_Yield.
+** The instruction at the address in register P1 is an Yield.
-** Jump to the P2 parameter of that OP_Yield.
+** Jump to the P2 parameter of that Yield.
 ** After the jump, register P1 becomes undefined.
+**
+** See also: InitCoroutine
 */
 case OP_EndCoroutine: {           /* in1 */
   VdbeOp *pCaller;
@@ -807,11 +811,16 @@ case OP_EndCoroutine: {           /* in1 */
 
 /* Opcode:  Yield P1 P2 * * *
 **
-** Swap the program counter with the value in register P1.
+** Swap the program counter with the value in register P1.  This
+** has the effect of yielding to a coroutine.
 **
-** If the co-routine ends with OP_Yield or OP_Return then continue
+** If the coroutine that is launched by this instruction ends with
-** to the next instruction.  But if the co-routine ends with
+** Yield or Return then continue to the next instruction.  But if
-** OP_EndCoroutine, jump immediately to P2.
+** the coroutine launched by this instruction ends with
+** EndCoroutine, then jump to P2 rather than continuing with the
+** next instruction.
+**
+** See also: InitCoroutine
 */
 case OP_Yield: {            /* in1, jump */
   int pcDest;
@@ -2196,10 +2205,14 @@ case OP_BitNot: {             /* same as TK_BITNOT, in1, out2 */
 
 /* Opcode: Once P1 P2 * * *
 **
-** Check if OP_Once flag P1 is set. If so, jump to instruction P2. Otherwise,
+** Check the "once" flag number P1. If it is set, jump to instruction P2. 
-** set the flag and fall through to the next instruction.  In other words,
+** Otherwise, set the flag and fall through to the next instruction.
-** this opcode causes all following opcodes up through P2 (but not including
+** In other words, this opcode causes all following opcodes up through P2
-** P2) to run just once and to be skipped on subsequent times through the loop.
+** (but not including P2) to run just once and to be skipped on subsequent
+** times through the loop.
+**
+** All "once" flags are initially cleared whenever a prepared statement
+** first begins to run.
 */
 case OP_Once: {             /* jump */
   assert( pOp->p1<p->nOnceFlag );
@@ -3495,7 +3508,7 @@ case OP_Close: {
 **
 ** This opcode leaves the cursor configured to move in forward order,
 ** from the begining toward the end.  In other words, the cursor is
-** configured to use OP_Next, not OP_Prev.
+** configured to use Next, not Prev.
 **
 ** See also: Found, NotFound, SeekLt, SeekGt, SeekLe
 */
@@ -3513,7 +3526,7 @@ case OP_Close: {
 **
 ** This opcode leaves the cursor configured to move in forward order,
 ** from the begining toward the end.  In other words, the cursor is
-** configured to use OP_Next, not OP_Prev.
+** configured to use Next, not Prev.
 **
 ** See also: Found, NotFound, SeekLt, SeekGe, SeekLe
 */
@@ -3531,7 +3544,7 @@ case OP_Close: {
 **
 ** This opcode leaves the cursor configured to move in reverse order,
 ** from the end toward the beginning.  In other words, the cursor is
-** configured to use OP_Prev, not OP_Next.
+** configured to use Prev, not Next.
 **
 ** See also: Found, NotFound, SeekGt, SeekGe, SeekLe
 */
@@ -3549,7 +3562,7 @@ case OP_Close: {
 **
 ** This opcode leaves the cursor configured to move in reverse order,
 ** from the end toward the beginning.  In other words, the cursor is
-** configured to use OP_Prev, not OP_Next.
+** configured to use Prev, not Next.
 **
 ** See also: Found, NotFound, SeekGt, SeekGe, SeekLt
 */
@@ -4470,7 +4483,7 @@ case OP_NullRow: {
 **
 ** This opcode leaves the cursor configured to move in reverse order,
 ** from the end toward the beginning.  In other words, the cursor is
-** configured to use OP_Prev, not OP_Next.
+** configured to use Prev, not Next.
 */
 case OP_Last: {        /* jump */
   VdbeCursor *pC;
@@ -4530,7 +4543,7 @@ case OP_Sort: {        /* jump */
 **
 ** This opcode leaves the cursor configured to move in forward order,
 ** from the begining toward the end.  In other words, the cursor is
-** configured to use OP_Next, not OP_Prev.
+** configured to use Next, not Prev.
 */
 case OP_Rewind: {        /* jump */
   VdbeCursor *pC;
@@ -4571,9 +4584,9 @@ case OP_Rewind: {        /* jump */
 ** to the following instruction.  But if the cursor advance was successful,
 ** jump immediately to P2.
 **
-** The OP_Next opcode is only valid following an OP_SeekGT, OP_SeekGE, or
+** The Next opcode is only valid following an SeekGT, SeekGE, or
-** OP_Rewind opcode used to position the cursor.  OP_Next is not allowed
+** OP_Rewind opcode used to position the cursor.  Next is not allowed
-** to follow OP_SeekLT, OP_SeekLE, or OP_Last.
+** to follow SeekLT, SeekLE, or OP_Last.
 **
 ** The P1 cursor must be for a real table, not a pseudo-table.  P1 must have
 ** been opened prior to this opcode or the program will segfault.
@@ -4593,7 +4606,7 @@ case OP_Rewind: {        /* jump */
 */
 /* Opcode: NextIfOpen P1 P2 P3 P4 P5
 **
-** This opcode works just like OP_Next except that if cursor P1 is not
+** This opcode works just like Next except that if cursor P1 is not
 ** open it behaves a no-op.
 */
 /* Opcode: Prev P1 P2 P3 P4 P5
@@ -4604,9 +4617,9 @@ case OP_Rewind: {        /* jump */
 ** jump immediately to P2.
 **
 **
-** The OP_Prev opcode is only valid following an OP_SeekLT, OP_SeekLE, or
+** The Prev opcode is only valid following an SeekLT, SeekLE, or
-** OP_Last opcode used to position the cursor.  OP_Prev is not allowed
+** OP_Last opcode used to position the cursor.  Prev is not allowed
-** to follow OP_SeekGT, OP_SeekGE, or OP_Rewind.
+** to follow SeekGT, SeekGE, or OP_Rewind.
 **
 ** The P1 cursor must be for a real table, not a pseudo-table.  If P1 is
 ** not open then the behavior is undefined.
@@ -4624,7 +4637,7 @@ case OP_Rewind: {        /* jump */
 */
 /* Opcode: PrevIfOpen P1 P2 P3 P4 P5
 **
-** This opcode works just like OP_Prev except that if cursor P1 is not
+** This opcode works just like Prev except that if cursor P1 is not
 ** open it behaves a no-op.
 */
 case OP_SorterNext: {  /* jump */
@@ -5145,7 +5158,8 @@ case OP_LoadAnalysis: {
 **
 ** Remove the internal (in-memory) data structures that describe
 ** the table named P4 in database P1.  This is called after a table
-** is dropped in order to keep the internal representation of the
+** is dropped from disk (using the Destroy opcode) in order to keep 
+** the internal representation of the
 ** schema consistent with what is on disk.
 */
 case OP_DropTable: {
@@ -5157,7 +5171,8 @@ case OP_DropTable: {
 **
 ** Remove the internal (in-memory) data structures that describe
 ** the index named P4 in database P1.  This is called after an index
-** is dropped in order to keep the internal representation of the
+** is dropped from disk (using the Destroy opcode)
+** in order to keep the internal representation of the
 ** schema consistent with what is on disk.
 */
 case OP_DropIndex: {
@@ -5169,7 +5184,8 @@ case OP_DropIndex: {
 **
 ** Remove the internal (in-memory) data structures that describe
 ** the trigger named P4 in database P1.  This is called after a trigger
-** is dropped in order to keep the internal representation of the
+** is dropped from disk (using the Destroy opcode) in order to keep 
+** the internal representation of the
 ** schema consistent with what is on disk.
 */
 case OP_DropTrigger: {