Re: [xml] xmlwriter function naming convention

[Daniel Veillard <veillard redhat com>]

On Mon, Feb 11, 2008 at 04:47:05PM -0500, Chase Douglas wrote:
> Hello,
>
> 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
> resources.
>
> 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 xmlsoft.org (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 
functions.

Daniel

-- 
Red Hat Virtualization group http://redhat.com/virtualization/
Daniel Veillard      | virtualization library  http://libvirt.org/
veillard redhat com  | libxml GNOME XML XSLT toolkit  http://xmlsoft.org/
http://veillard.com/ | Rpmfind RPM search engine  http://rpmfind.net/