==========================
 GNet Documentation notes
==========================

gtk-doc is required to build the documentation.  Only developers would
need to build the docs.  All distributions should include the docs
pre-built. This will be the case if you create the distribution tarball
with 'make distcheck'.


If gtk-doc is available and the version requirements are met, the 
documentation will be built automatically when make descends into
the doc directory.

=====================================
 Style notes for inline documentation
======================================

* Arguments 

  @arg: argument argument

  - The first word is not capitalized.
  - There is no period.
  - If the first argument is a "this" pointer, the description can be
	"a #Type" most of the time.
  - hostname should be described as "host name"

  Also note:
  - Parameter names should be as descriptive as possible.  Use
    words instead of abbreviations.  E.g.:
      * "buffer" instead of "buf"
      * "length" instead of "len"

    Exceptions: 
      * "src" and "dst" are ok.  
      * Use "iface" instead of "interface".  "interface" is a reserved
	  word for some compilers.

    (We break these rules a lot.)


* Return values

  Returns: something.  Something else happens.

  - The first word is not capitalized
  - There is a period so that the first sentence reads as a sentence
  - There can be more than one sentence.


* Descriptions

 The first sentence should be in the form: "Does something to a #X."

 Examples:

 x_new: Creates a #X [from ...].  Returns: a new #X.
 x_clone: Copies a #X.  Returns: a copy of @x.
 x_delete: Deletes a #X.
 x_hash: Creates a hash code for a #X for use with GHashTable.
	Returns: the hash code for @x.
 x_equal: Compares two #Xs for equality.  Returns: TRUE if they are
	equal; FALSE otherwise.  (args are "a #X" and "another #X"
 x_ref: Adds a reference to a #X.
 x_unref: Removes a reference from a #X.  A #X is deleted when
 	the reference count reaches 0.



TODO:
  failure vs. error - is there a difference?