Re: [xml] xmlwriter function naming convention

["Mickautsch, Alfred" <alfred mickautsch schuler-ag com>]

> -----Ursprüngliche Nachricht-----
> Von: xml-bounces gnome org [mailto:xml-bounces gnome org] Im Auftrag von
> Chase Douglas
> Gesendet: Montag, 11. Februar 2008 22:47
> An: xml gnome org
> Betreff: [xml] xmlwriter function naming convention
>
> 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.

Well, the writer uses a xmlOutputBuffer as an output stream and this one is doing all the buffering. With 
xmlTextWriterFlush you can flush the buffer at any point in your code.

> I propose that xmlFreeTextWriter be renamed to xmlCloseTextWriter. This
> 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.

Since xmlFreeTextWriter behaves more like a destructor it could as well be called xmlDeleteTextWriter. From 
another point of view, maybe xmlTextWriterEndDocument should call xmlTextWriterFlush, so there would be no 
need for xmlOutputBufferClose to flush the buffer itself and the behaviour of xmlFreeTextWriter would match 
the behaviour you expect from it.

> 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.

Anyway, you can rename the function as you like if you make shure, there will be no ABI problem.

Servus -- Alfred

--
Alfred Mickautsch

Schuler Business Solutions AG
Karl-Berner-Str. 4
D-72285 Pfalzgrafenweiler
tel:    +49 (0)74 45 830-184
fax:    +49 (0)74 45 830-349
e-mail: alfred mickautsch schuler-ag com