[xml] xmlwriter function naming convention

[Chase Douglas <chasedouglas gmail com>]

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

Thank you,
Chase