[GLIB Documentation] Improved Source docs for Glib?

[Ryan McDougall <ryan mcdougall telusplanet net>]

Hello,
	Whenever I learn new source, I like to annotate it with comments on
stuff I learn as I learn it. I find that this more beginner level of
commenting helps myself and others learn the source. Basically, if I go
through and improve the comments as I go should I submit patches for the
main tree? Are you guys interested in documentation patches?

Below is a first stab at introductory comments for giochannel.h:

"The Glib Input/Output Channel is designed to provide an abstract layer
for character oriented input and output streams. In most operating
systems character streams are implemented as files, and Glib I/O
Channels are the preferred method of doing file I/O using Glib. All
reads and writes to a channel are respectively buffered.

The giochannel API has extensive error checking and management
facilities, including return and status codes. All I/O functions that
can fail return GError objects which detail the error encountered, and
must always be checked. Please see gerror for more information about
Glib's error faculties.

Glib I/O Channels integrate easily into Glib's own event based loops via
the channel "watches", which will send events to a GMainLoop whenever
there is data available to be either read or written. Please see gmain
for more information about Glib's event loop faculties.

The design of Glib's I/O Channel is very closely tied to UNIX-like
files, and file systems. As such the giochannel interface supports
reading and writing either ASCII or Unicode formatted characters,
line-based reads and writes, opening and closing character streams,
seeking through character streams, and flushing caching buffers.

As a consequence of this design, I/O Channels can be created using UNIX
sockets, which transparently allow fast communication with both local
and remote processes. Also, I/O Channels can make use of any named file
that is made available by a file system, and thus subject to the
particular performance characteristics of the specific file system.

Although Glib is designed to be cross-platform compatible, there are
areas where UNIX file semantics do not translate well. Please read below
carefully for platform specific functions which allow I/O Channels to
integrate with your existing system."

Keep in mind that the above is just the introduction that goes below the
GPL header.

Cheers,
Ryan