libgimp: move docs from template files to inline comments

Also split up the "tools" docs into separate files so it matches
the new autogenerated PDB section headers.

libgimp/gimp.c

@@ -105,6 +105,17 @@
 #include "libgimp-intl.h"
 
 
+/**
+ * SECTION: gimp
+ * @title: Gimp
+ * @short_description: Main functions needed for building a GIMP plug-in.
+ *                     This header includes all other GIMP Library headers.
+ *
+ * Main functions needed for building a GIMP plug-in. This header
+ * includes all other GIMP Library headers.
+ **/
+
+
 #define TILE_MAP_SIZE (_tile_width * _tile_height * 4)
 
 #define ERRMSG_SHM_FAILED "Could not attach to gimp shared memory segment"
@@ -222,7 +233,8 @@ static gchar             *pdb_error_message  = NULL;
  * The main procedure that must be called with the PLUG_IN_INFO structure
  * and the 'argc' and 'argv' that are passed to "main".
  *
- * Return value:
+ * Returns: an exit status as defined by the C library,
+ *          on success %EXIT_SUCCESS.
  **/
 gint
 gimp_main (const GimpPlugInInfo *info,