Re: [xml] xmlwriter function naming convention

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


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

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

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