Commits

Lars Kanis committed b7633be Draft

Polish the documentation a little bit

Comments (0)

Files changed (1)

ext/pg_connection.c

  *
  * When using a custom row processor, row data is not accumulated into the
  * PG::Result, so the PG::Result ultimately delivered to the application will
- * contain no rows (ntuples = 0). However, it still has
- * PG::Result#result_status = PGRES_TUPLES_OK, and it contains correct
+ * contain no rows (PG::Result#ntuples => 0). However, it still has
+ * PG::Result#result_status => PGRES_TUPLES_OK, and it contains correct
  * information about the set of columns in the query result.
  * On the other hand, if the query fails partway through, the returned
- * PG::Result has result_status = PGRES_FATAL_ERROR. The application must
- * be prepared to undo any actions of the row processor whenever it gets
- * a PGRES_FATAL_ERROR result.
+ * PG::Result has PG::Result#result_status => PGRES_FATAL_ERROR.
+ * The application must be prepared to undo any actions of the row processor
+ * whenever it gets a PGRES_FATAL_ERROR result.
  *
- * This function takes a block, which should
- * accept a two parameters that will be a PG::Result object and an Array of
- * the values of the given row. The block should return nil in case of success
+ * This function takes a block, which should accept a two parameters that will
+ * be a PG::Result object and a +nil+ or +Array+ object. If you pass no arguments,
+ * it will reinstall the standard row processor on the given connection.
+ *
+ * Immediately after pg has determined the result set's column information,
+ * it will make a call to the row processor with +row+ set to +nil+.
+ * The row processor can use this call to initialize for a new result set;
+ * if it has nothing to do, it can just return. In subsequent calls, one per
+ * received row, +row+ is an Array of Strings containing the column values.
+ *
+ * The block should return nil in case of success
  * and a error String in case of failure. In the error case, all remaining rows
  * in the result set are discarded and then a PGRES_FATAL_ERROR PG::Result
  * is returned to the application (containing the specified error message).
  *
- * If you pass no arguments, it will reinstall the standard row processor
- * on the given connection.
- *
- * *Note:* The result object passed to the block should not be used outside
+ * *Note:* The +result+ passed to the block should not be used outside
  * of the block, since the corresponding C object could be freed after the
  * block finishes.
  *
  * call-seq:
  *   conn.get_row_processor() -> Proc
  *
- * Returns the Proc object previously set by {set_row_processor},
+ * Returns the Proc object previously set by #set_row_processor,
  * or +nil+ if it was previously the default.
  */
 static VALUE
  * This is a simple convenience function to discard incoming data after
  * a row processor has failed or it's determined that the rest of the
  * result set is not interesting. +skip_result+ is exactly equivalent to
- * {get_result} except that it transiently installs a dummy row processor
+ * #get_result except that it transiently installs a dummy row processor
  * function that just discards data.
  * 
  */