Re: [xml] xmlwriter function naming convention

On Mon, Feb 11, 2008 at 04:47:05PM -0500, Chase Douglas wrote:

After a lengthy discussion today on the #irc with DV (thanks again, even
though it was frustrating at points), I realized that I was
misunderstanding what the xmlFreeTextWriter function did.
xmlFreeTextWriter currently flushes out the writer buffer to the
associated stream and then deallocates resources associated with the
writer. My assumption was that data was being written directly to the
associated output stream without any buffering inside the writer.

I propose that xmlFreeTextWriter be renamed to xmlCloseTextWriter. This

  Yes that would make sense for the reasons exposed, except that one cannot
change published APIs, and merely aliasing xmlFreeTextWriter to
xmlCloseTextWriter just increase the entry point.
  I still think 'Free' in the name makes sense because a lot of data
structures are freed in the operation (one or 2 buffers, the writer structure
and also the data associated to the ongoing character conversion if any,
as well as I/O buffer and potentially FTP/HTTP states).
  Explaining that this function does a Flush might help.

follows the convention of file I/O through stdio. After fopen(), one
uses the fclose() function to flush out the buffers and deallocate
resources. One cannot use free() on the file pointer without potentially
disasterous results. This is the distinction between a "close" function
and a "free" function. A "close" function flushes data from buffers
before freeing resources, whereas a "free" function only frees

Further, I feel that the naming convention is more important for libxml2
than other libraries as there is currently no documentation outside of
the writer.c example given on (which does not point out the
buffer flushing aspect of xmlFreeTextWriter), and the xmlwriter API
(which only notes that xmlFreeTextWriter deallocates resources
associated with the writer).

My thoughts are that this name clarification will lead to a better
understanding of the use of the xmlwriter library, especially given the
current documentation available to the end user. It may also help to add
the flushing aspect to the API documentation for the function as well.

  Yes the Flush side-effect could be added. i think you main misunderstanding
came from the fact that all operations are buffered, that was obvious to
me for I/O and charset conversion aspects, and that even if saving to a 
memory buffer. That could be added in the documentation of the creation 


Red Hat Virtualization group
Daniel Veillard      | virtualization library
veillard redhat com  | libxml GNOME XML XSLT toolkit | Rpmfind RPM search engine

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]