[cl-debian] Bug#349778: Documentation for pg-close-portal wrong

[debian.mexon at spamgourmet.com]

Package: cl-pg
Version: 20050717-1

These two functions have identical documentation.  If they implement 
identical functionality, then one should be deleted; if they implement 
different functionality, the documentation should explain the difference:

(defgeneric pg-close-statement (connection statement-name)
   (:documentation
    "Closes a prepared statement"))

(defgeneric pg-close-portal (connection portal)
   (:documentation
    "Closes a prepared statement"))

So yes, I know that one closes a statement, while the other closes a 
portal.  But I don't know what a portal is, I don't know what "close" 
means ("delete"? "forget about"? "prevent updates of"? "wrap inside a 
closure"?) and pg-close-statement isn't doing what I expect it to do (I 
get errors saying that the statement already exists when I try to 
re-create it afterwards).  I don't have enough information to verify 
that the functions are doing what they're supposed to do.  They should 
certainly include references to whichever function "opens" the things 
that they are closing.

Also, the start of the file recommends seeing the README:

;; See the README for API documentation.

...but no README is included.  I've chased up the README from CVS, and 
in fact it provides no help here.  But it should probably be included 
anyway, with a disclaimer saying that it's out of date.

Even better, it would be nice if there was some actual real 
documentation provided, including examples of how each of the functions 
is supposed to be used.  Right now, I'm just having to guess how to use 
prepared statements, and after a couple of days of bashing my head 
against the problem I still can't get it to work.