+//! Returns +//! @ol +//! @item +//! The result as an array of mappings indexed on the name +//! of the columns. +//! @item +//! 0 if the query didn't return any result (e.g. INSERT or similar). +//! @item +//! Throws an exception if the query fails.

I'd prefer use of semantic markup. eg:

//! @returns //! Returns one of the following on success: //! @mixed //! @type array(mapping(string:string)) //! The result as an array of mappings indexed on the name //! of the columns. //! @type zero //! The value @expr{0@} (zero) if the query didn't return any //! result (eg @tt{INSERT@} or similar). //! @endmixed //! //! @throws //! Throws an exception if the query fails.

/ Henrik Grubbström (Lysator)

Previous text:

2003-10-22 00:50: Subject: Proposal-patch for documentation of Sql.pike

---

$ cvs diff -u Sql.pike Index: Sql.pike =================================================================== RCS file: /cvs/Pike/7.5/lib/modules/Sql.pmod/Sql.pike,v retrieving revision 1.68 diff -u -r1.68 Sql.pike --- Sql.pike 30 Jul 2003 02:30:33 -0000 1.68 +++ Sql.pike 21 Oct 2003 22:48:00 -0000 @@ -340,9 +340,16 @@ return ({sprintf(query,@args), b}); }

-//! Send an SQL query to the underlying SQL-server. The result is returned -//! as an array of mappings indexed on the name of the columns. -//! Returns 0 if the query didn't return any result (e.g. INSERT or similar). +//! Send an SQL query to the underlying SQL-server. +//! Returns +//! @ol +//! @item +//! The result as an array of mappings indexed on the name +//! of the columns. +//! @item +//! 0 if the query didn't return any result (e.g. INSERT or similar). +//! @item +//! Throws an exception if the query fails. //! //! @param q //! Query to send to the SQL-server. This can either be a string with the @@ -359,8 +366,12 @@ //! the variable is used. //! //! @code -//! query("select foo from bar where gazonk=:baz", -//! ([":baz":"value"])) ) +//! mixed err = catch { +//! query("SELECT foo FROM bar WHEREe gazonk=:baz", +//! ([":baz":"value"])); +//! }; +//! if(intp(err)) +//! werror("An error occured."); //! @endcode //! //! Binary values (BLOBs) may need to be placed in multisets.

/ Peter Lundqvist (disjunkt)