Re: Bonobo Docs Cleanup

From: "John R. Sheets" <dusk ravendusk org>
To: gnome-components-list gnome org
Subject: Re: Bonobo Docs Cleanup
Date: Thu, 22 Feb 2001 11:43:17 -0600

On Feb 21, 2001, "John R. Sheets" <dusk ravendusk org> wrote:
> 
> Hi,
> 
> Just a few touchups after the recent barrage of new docs.  (c:

Here's an improved version of the previous patch, which also includes
many copy-editing fixes for the API docs.  It should only affect C
comments and SGML files.  FYI, this covers the docs from BonoboObject
to BonoboEmbeddable.  I'll submit the rest (BonoboView to
bonobo-async) in a separate patch, when I'm done proofreading it.

Can I commit this?

John

-- 
dusk ravendusk org                            http://www.gnome.org
jsheets codeweavers com                  http://www.worldforge.org
jsheets users sourceforge net     http://openbooks.sourceforge.net
               http://advogato.org/person/jsheets

                   Writing GNOME Applications
          http://www.aw.com/cseng/titles/0-201-65791-0/

Index: ChangeLog
===================================================================
RCS file: /cvs/gnome/bonobo/ChangeLog,v
retrieving revision 1.989
diff -u -r1.989 ChangeLog
--- ChangeLog	2001/02/21 17:19:14	1.989
+++ ChangeLog	2001/02/22 17:34:05
@@ -1,3 +1,32 @@
+2001-02-21  John R. Sheets  <dusk ravendusk org>
+
+	* bonobo/bonobo-stream-client.c, bonobo/bonobo-persist-stream.c,
+	bonobo/bonobo-listener.c, bonobo/bonobo-event-source.c,
+	bonobo/bonobo-transient.c, bonobo/bonobo-property-bag-xml.c,
+	bonobo/bonobo-arg.c, bonobo/bonobo-property-bag-client.c,
+	bonobo/bonobo-exception.c, bonobo/bonobo-object-client.c,
+	bonobo/bonobo-main.c, bonobo/bonobo-xobject.c,
+	bonobo/bonobo-object.c,
+	doc/api/tmpl/bonobo-event-source.sgml,
+	doc/api/tmpl/bonobo-property-bag-xml.sgml,
+	doc/api/tmpl/bonobo-property-bag-client.sgml,
+	doc/api/tmpl/bonobo-property-bag.sgml,
+	doc/api/tmpl/bonobo-exception.sgml,
+	doc/api/tmpl/bonobo-generic-factory.sgml,
+	doc/api/tmpl/bonobo-xobject.sgml,
+	doc/api/tmpl/bonobo-listener.sgml: Minor spelling/grammar tweaks
+	to inline comments.
+
+	* doc/api/tmpl/bonobo-transient.sgml: Changed invalid <variable>
+	tag to <parameter>.
+
+	* doc/api/tmpl/bonobo-property-bag-xml.sgml,
+	doc/api/tmpl/bonobo-xobject.sgml,
+	doc/api/tmpl/bonobo-moniker-util.sgml: Use "&amp;" instead of "&".
+
+	* doc/api/tmpl/bonobo-context.sgml: Changed an errant </a> to
+	</title>.  Added <para> tags around <listitem> contents.
+
 2001-02-21  Michael Meeks  <michael ximian com>
 
 	* samples/controls/bonobo-clock-control.c
Index: bonobo/bonobo-arg.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-arg.c,v
retrieving revision 1.14
diff -u -r1.14 bonobo-arg.c
--- bonobo/bonobo-arg.c	2001/02/21 00:21:59	1.14
+++ bonobo/bonobo-arg.c	2001/02/22 17:34:05
@@ -19,7 +19,7 @@
  * @t: the BonoboArgType eg. TC_long
  * 
  * Create a new BonoboArg with the specified type
- * the value of the BonoboArg is initialy empty.
+ * the value of the BonoboArg is initially empty.
  * 
  * Return value: 
  **/
@@ -224,7 +224,7 @@
  * @a: pointer to blank BonoboArg
  * @arg: GtkArg to copy
  * 
- * This maps a GtkArg @arg to a BonoboArg @a,
+ * This maps a GtkArg @arg to a BonoboArg @a;
  * @a must point to a freshly allocated BonoboArg
  * eg. such as returned by bonobo_arg_new
  **/
@@ -299,7 +299,7 @@
  * @a: pointer to a blank GtkArk
  * @arg: the BonoboArg to copy
  * 
- * Maps a BonoboArg to a GtkArg, @a must point
+ * Maps a BonoboArg to a GtkArg; @a must point
  * to a blank GtkArg.
  **/
 void
@@ -358,8 +358,8 @@
  * @b: a type code
  * @opt_ev: optional exception environment or NULL.
  * 
- * This compares two BonoboArgType's in @a and @b,
- * the @opt_ev is an optional CORBA_Environment for
+ * This compares two BonoboArgType's in @a and @b.
+ * The @opt_ev is an optional CORBA_Environment for
  * exceptions, or NULL. This function is commutative.
  * 
  * Return value: TRUE if equal, FALSE if different
@@ -390,7 +390,7 @@
  * @b: another bonobo arg
  * @opt_ev: optional exception environment or NULL.
  * 
- * Compares two BonoboArgs for equivalence, will return TRUE
+ * Compares two BonoboArgs for equivalence; will return TRUE
  * if equivalent for all simple cases. For Object references
  * CORBA sometimes denies 2 object references are equivalent
  * even if they are [ this is a feature_not_bug ].
Index: bonobo/bonobo-embeddable.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-embeddable.c,v
retrieving revision 1.64
diff -u -r1.64 bonobo-embeddable.c
--- bonobo/bonobo-embeddable.c	2001/02/21 10:19:27	1.64
+++ bonobo/bonobo-embeddable.c	2001/02/22 17:34:05
@@ -548,7 +548,7 @@
  * @fn: function to be invoked for each existing BonoboView
  * @data: data to pass to function
  *
- * Invokes the @fn function for each view existing
+ * Invokes the @fn function for each existing view.
  */
 void
 bonobo_embeddable_foreach_view (BonoboEmbeddable *embeddable,
@@ -574,7 +574,7 @@
  * @fn: function to be invoked for each existing GnomeItem
  * @data: data to pass to function
  *
- * Invokes the @fn function for each item existing
+ * Invokes the @fn function for each existing item.
  */
 void
 bonobo_embeddable_foreach_item (BonoboEmbeddable *embeddable,
Index: bonobo/bonobo-event-source.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-event-source.c,v
retrieving revision 1.20
diff -u -r1.20 bonobo-event-source.c
--- bonobo/bonobo-event-source.c	2001/02/15 21:07:30	1.20
+++ bonobo/bonobo-event-source.c	2001/02/22 17:34:05
@@ -135,7 +135,7 @@
 /**
  * bonobo_event_source_notify_listeners:
  * @event_source: the Event Source that will emit the event.
- * @event_name: Name of the event being emmited
+ * @event_name: Name of the event being emitted
  * @value: A CORBA_any value that contains the data that is passed to interested clients
  * @opt_ev: A CORBA_Environment where a failure code can be returned, can be NULL.
  *
Index: bonobo/bonobo-exception.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-exception.c,v
retrieving revision 1.12
diff -u -r1.12 bonobo-exception.c
--- bonobo/bonobo-exception.c	2001/02/21 12:42:55	1.12
+++ bonobo/bonobo-exception.c	2001/02/22 17:34:05
@@ -255,11 +255,13 @@
  * bonobo_exception_get_text:
  * @ev: the corba environment.
  * 
- * Returns a user readable description of the exception, busks
- * something convincing if it is not know.
+ * Returns a user readable description of the exception.  First
+ * checks @ev against builtin Bonobo exceptions, then falls back to
+ * exception names added through bonobo_exception_add_handler_str
+ * or bonobo_exception_add_handler_fn.
  * 
- * Return value: a g_malloc'd description; needs freeing as,
- * and when. NULL is never returned.
+ * Return value: A g_malloc'd description, which the caller must free.
+ * NULL is never returned.
  **/
 char *
 bonobo_exception_get_text (CORBA_Environment *ev)
Index: bonobo/bonobo-listener.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-listener.c,v
retrieving revision 1.17
diff -u -r1.17 bonobo-listener.c
--- bonobo/bonobo-listener.c	2001/02/13 22:11:51	1.17
+++ bonobo/bonobo-listener.c	2001/02/22 17:34:05
@@ -145,8 +145,8 @@
  * @kind: the kind of the event
  * @subtype: an optional subtype
  *
- * Creates an event name. Event names consists of three part. The @idl_path is
- * mainly to create an unique namespace, and should identify the interface 
+ * Creates an event name. Event names consist of three parts. The @idl_path is
+ * mainly to create a unique namespace, and should identify the interface 
  * which triggered the event, for example "Bonobo/Property". The @kind denotes
  * what happened, for example "change". Finally you can use the optional 
  * @subtype to make events more specific. All three parts of the name are 
Index: bonobo/bonobo-main.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-main.c,v
retrieving revision 1.38
diff -u -r1.38 bonobo-main.c
--- bonobo/bonobo-main.c	2001/01/13 17:39:29	1.38
+++ bonobo/bonobo-main.c	2001/02/22 17:34:06
@@ -93,10 +93,10 @@
  *
  * To do graphical embedding in the X window system, Bonobo
  * uses the classic foreign-window-reparenting trick.  The
- * GtkPlug/GtkSocket widgets are used for thise purpose.  However,
+ * GtkPlug/GtkSocket widgets are used for this purpose.  However,
  * serious robustness problems arise if the GtkSocket end of the
  * connection unexpectedly dies.  The X server sends out DestroyNotify
- * events for the descendents of the GtkPlug (i.e., your embedded
+ * events for the descendants of the GtkPlug (i.e., your embedded
  * component's windows) in effectively random order.  Furthermore, if
  * you happened to be drawing on any of those windows when the
  * GtkSocket was destroyed (a common state of affairs), an X error
@@ -233,7 +233,7 @@
 /**
  * bonobo_activate:
  *
- * Activates the Bonobo POA manager registered by bonobo_init
+ * Activates the Bonobo POA manager registered by bonobo_init.
  * This should be called at the end of application initialization.
  * You do not need to call this function if you use bonobo_main().
  * 
Index: bonobo/bonobo-moniker-util.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-moniker-util.c,v
retrieving revision 1.31
diff -u -r1.31 bonobo-moniker-util.c
--- bonobo/bonobo-moniker-util.c	2001/02/21 00:21:59	1.31
+++ bonobo/bonobo-moniker-util.c	2001/02/22 17:34:06
@@ -117,7 +117,7 @@
  *  This routine is used to continue building up the chain
  * that forms a multi-part moniker. The parent is referenced
  * as the parent and passed onto the next stage of parsing
- * the 'name'. We eventualy return a moniker handle which
+ * the 'name'. We eventually return a moniker handle which
  * represents the end of a linked list of monikers each
  * pointing to their parent:
  *
Index: bonobo/bonobo-object-client.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-object-client.c,v
retrieving revision 1.54
diff -u -r1.54 bonobo-object-client.c
--- bonobo/bonobo-object-client.c	2001/02/21 12:42:55	1.54
+++ bonobo/bonobo-object-client.c	2001/02/22 17:34:06
@@ -48,7 +48,7 @@
  * @iid: an OAFIID
  * @oaf_flags: activation flags
  *
- * This activates the object from the IID using oaf; you probably
+ * This activates the object from the IID using OAF; you probably
  * don't want to do this, you might want to use bonobo_get_object
  * which does object activation through the moniker system.
  * 
@@ -118,9 +118,9 @@
  * @callback: a callback function
  * @user_data: user data
  *
- *   This activates the object from the IID using oaf; you probably
+ *   This activates the object from the IID using OAF; you probably
  * don't want to do this; instead do capability based activation
- * using Oaf directly.
+ * using OAF directly.
  */
 void
 bonobo_object_activate_async (const char                    *iid,
@@ -172,7 +172,7 @@
  * @opt_ev: optional exception environment, or NULL
  * 
  * Queries the object to see if it implements the interface
- * described by @interface_desc. Basicaly a thin
+ * described by @interface_desc. Basically a thin
  * Bonobo_Unknown::query_interface wrapper.
  * 
  * Return value: A valid Bonobo_Unknown reference or
@@ -221,7 +221,7 @@
  * @opt_ev: optional exception environment, or NULL
  * 
  * Queries the object to see if it implements the interface
- * described by @interface_desc. Basicaly a thin
+ * described by @interface_desc. Basically a thin
  * Bonobo_Unknown::query_interface wrapper.
  * 
  * Return value: TRUE if the interface is available else FALSE.
@@ -280,7 +280,7 @@
  * @object_client: the object client
  * @opt_exception_obj: optional CORBA exception environment
  * 
- * Increments the Bonobo ref count on the remote object
+ * Increments the Bonobo ref count on the remote object.
  **/
 void
 bonobo_object_client_ref (BonoboObjectClient *object_client,
@@ -311,7 +311,7 @@
  * @object_client: the object client
  * @opt_exception_obj: optional CORBA exception environment
  * 
- * Decrements the Bonobo ref count on the remote object
+ * Decrements the Bonobo ref count on the remote object.
  **/
 void
 bonobo_object_client_unref (BonoboObjectClient *object_client,
Index: bonobo/bonobo-object.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-object.c,v
retrieving revision 1.101
diff -u -r1.101 bonobo-object.c
--- bonobo/bonobo-object.c	2001/02/14 21:49:11	1.101
+++ bonobo/bonobo-object.c	2001/02/22 17:34:06
@@ -235,7 +235,7 @@
  * bonobo_object_ref:
  * @object: A BonoboObject you want to ref-count
  *
- * increments the reference count for the aggregate BonoboObject.
+ * Increments the reference count for the aggregate BonoboObject.
  */
 void
 bonobo_object_ref (BonoboObject *object)
@@ -257,7 +257,7 @@
  * bonobo_object_unref:
  * @object: A BonoboObject you want to unref.
  *
- * decrements the reference count for the aggregate BonoboObject.
+ * Decrements the reference count for the aggregate BonoboObject.
  */
 void
 bonobo_object_unref (BonoboObject *object)
@@ -378,7 +378,7 @@
  *   This function returns a duplicated CORBA Object reference;
  * it also bumps the ref count on the object. This is ideal to
  * use in any method returning a Bonobo_Object in a CORBA impl.
- * if object is CORBA_OBJECT_NIL it is returned unaffected.
+ * If object is CORBA_OBJECT_NIL it is returned unaffected.
  * 
  * Return value: duplicated & ref'd corba object reference.
  **/
@@ -416,7 +416,7 @@
  *   This function releases a CORBA Object reference;
  * it also decrements the ref count on the bonobo object.
  * This is the converse of bonobo_object_dup_ref. We
- * tolerate object == CORBA_OBJECT_NIL silently
+ * tolerate object == CORBA_OBJECT_NIL silently.
  **/
 void
 bonobo_object_release_unref (Bonobo_Unknown     object,
@@ -1174,8 +1174,8 @@
  * bonobo_object_list_unref_all:
  * @list: A list of BonoboObjects *s
  * 
- *  This routine unrefs all the objects listed in
- * the list and then removes them from @list: if
+ *  This routine unrefs all valid objects in
+ * the list and then removes them from @list if
  * they have not already been so removed.
  **/
 void
Index: bonobo/bonobo-persist-stream.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-persist-stream.c,v
retrieving revision 1.37
diff -u -r1.37 bonobo-persist-stream.c
--- bonobo/bonobo-persist-stream.c	2001/02/08 23:37:42	1.37
+++ bonobo/bonobo-persist-stream.c	2001/02/22 17:34:06
@@ -145,7 +145,7 @@
 
 /**
  * bonobo_persist_stream_construct:
- * @ps: A GnomerPersistStream object
+ * @ps: A BonoboPersistStream object
  * @load_fn: Loading routine
  * @save_fn: Saving routine
  * @closure: Data passed to IO routines.
@@ -214,7 +214,7 @@
 
 /**
  * bonobo_persist_stream_set_dirty:
- * @ps: A GnomerPersistStream object
+ * @ps: A BonoboPersistStream object
  * @dirty: A boolean value representing whether the object is dirty or not
  *
  * This routine sets the dirty bit for the PersistStream object.
Index: bonobo/bonobo-property-bag-client.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-property-bag-client.c,v
retrieving revision 1.28
diff -u -r1.28 bonobo-property-bag-client.c
--- bonobo/bonobo-property-bag-client.c	2001/02/21 10:19:28	1.28
+++ bonobo/bonobo-property-bag-client.c	2001/02/22 17:34:07
@@ -183,13 +183,14 @@
 
 /**
  * bonobo_property_bag_client_get_property:
- * @pb: A Bonobo_PropertyBag      which is associated with a remote
+ * @pb: A Bonobo_PropertyBag which is associated with a remote
  * BonoboPropertyBag.
  * @name: A string containing the name of the property which is to
  * be fetched.
  * @ev: optional CORBA exception environment or NULL
  *
- * Returns: A #Bonobo_Property CORBA object reference for the
+ * Returns: A #Bonobo_Property CORBA object reference corresponding
+ * to the requested property.
  *
  */
 Bonobo_Property
@@ -227,12 +228,12 @@
 
 /**
  * bonobo_property_bag_client_persist:
- * @pb: A #Bonobo_PropertyBag      object which is bound to a remote
+ * @pb: A #Bonobo_PropertyBag object which is bound to a remote
  * #Bonobo_PropertyBag server.
  * @stream: A #BonoboStream into which the data in @pb will be written.
  * @ev: optional CORBA exception environment or NULL
  *
- * Reads the property data stored in the #Bonobo_Property_bag to which
+ * Reads the property data stored in the #Bonobo_PropertyBag to which
  * @pb is bound and streams it into @stream.  The typical use for
  * this function is to save the property data for a given Bonobo
  * Control into a persistent store to which @stream is attached.
@@ -277,7 +278,7 @@
  * 
  *  Serializes the property bag @pb to the @stream,
  * using the PersistStream interface associated with the
- * PropertyBAg.
+ * PropertyBag.
  **/
 void
 bonobo_property_bag_client_depersist (Bonobo_PropertyBag       pb,
Index: bonobo/bonobo-property-bag-xml.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-property-bag-xml.c,v
retrieving revision 1.15
diff -u -r1.15 bonobo-property-bag-xml.c
--- bonobo/bonobo-property-bag-xml.c	2001/02/21 00:21:59	1.15
+++ bonobo/bonobo-property-bag-xml.c	2001/02/22 17:34:07
@@ -273,7 +273,7 @@
  * #BonoboUINode XML abstraction. @ev is used for flagging
  * any non-fatal exceptions during the process. On exception
  * NULL will be returned. opt_parent should be NULL, and is
- * used internaly for recursive tree construction.
+ * used internally for recursive tree construction.
  *
  * Both type and content data are dumped in a non-standard, but
  * trivial format.
@@ -666,8 +666,8 @@
  * @node: the parsed XML representation of an any
  * @ev: a corba exception environment
  * 
- * This routine is the converse of bonobo_property_bag_xml_encode_any
- * it hydrates a serialized CORBA_any.
+ * This routine is the converse of bonobo_property_bag_xml_encode_any.
+ * It hydrates a serialized CORBA_any.
  * 
  * Return value: the CORBA_any or NULL on error
  **/
Index: bonobo/bonobo-stream-client.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-stream-client.c,v
retrieving revision 1.15
diff -u -r1.15 bonobo-stream-client.c
--- bonobo/bonobo-stream-client.c	2001/01/23 23:48:40	1.15
+++ bonobo/bonobo-stream-client.c	2001/02/22 17:34:07
@@ -24,7 +24,7 @@
  * @size: number of bytes to write
  * @ev: a CORBA environment to return status information.
  *
- * This is a helper routine to write @size bytes from @buffer to the @stream
+ * This is a helper routine to write @size bytes from @buffer to the @stream.
  * It will continue to write bytes until a fatal error occurs.
  *
  */
Index: bonobo/bonobo-transient.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-transient.c,v
retrieving revision 1.13
diff -u -r1.13 bonobo-transient.c
--- bonobo/bonobo-transient.c	2001/02/07 03:06:58	1.13
+++ bonobo/bonobo-transient.c	2001/02/22 17:34:07
@@ -180,7 +180,7 @@
  * This function is only for wrappers and object derivation.  For normal
  * use, please see #bonobo_transient_new.
  *
- * This function will return %NULL on failiure, however it is your
+ * This function will return %NULL on failure; however it is your
  * responsibility to destroy the failed object in that case.
  *
  * Returns: a #BonoboTransient object (the @transient)
Index: bonobo/bonobo-xobject.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-xobject.c,v
retrieving revision 1.8
diff -u -r1.8 bonobo-xobject.c
--- bonobo/bonobo-xobject.c	2001/02/21 10:19:28	1.8
+++ bonobo/bonobo-xobject.c	2001/02/22 17:34:07
@@ -89,7 +89,7 @@
 			
 	if (klass->poa_fini_fn)
 		klass->poa_fini_fn (servant, &ev);
-	else /* Actualy quicker and nicer */
+	else /* Actually quicker and nicer */
 		PortableServer_ServantBase__fini (servant, &ev);
 			
 	CORBA_free (oid);
@@ -422,9 +422,9 @@
  * @p: a pointer to something
  * 
  * This function can be passed a BonoboXObject * or a
- * PortableServer_Servant, and it will return a BonoboXObject *
+ * PortableServer_Servant, and it will return a BonoboXObject *.
  * It also can convert a CORBA_Object to a BonoboXObject in
- * some circumstances, but this behavior is broken conceptualy.
+ * some circumstances, but this behavior is broken conceptually.
  * 
  * Return value: a BonoboXObject or NULL.
  **/
Index: doc/api/tmpl/bonobo-context.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-context.sgml,v
retrieving revision 1.6
diff -u -r1.6 bonobo-context.sgml
--- doc/api/tmpl/bonobo-context.sgml	2001/02/21 17:19:15	1.6
+++ doc/api/tmpl/bonobo-context.sgml	2001/02/22 17:34:08
@@ -12,12 +12,12 @@
 a single function, and yet have access to the whole
 Bonobo service framework. Two examples of this are the
 MonikerContext and the RunningContext ( see
-Bonobo_Context.idl )
+Bonobo_Context.idl ).
 </para>
 
 <para>
   <example>
-     <title>Getting and using the moniker context</a>
+     <title>Getting and using the moniker context</title>
      <programlisting>
 Bonobo_MonikerContext context;
 Bonobo_Unknown        object;
@@ -39,9 +39,15 @@
 currently there are the following:
   <itemizedlist>
     <listitem>
-      Activation - Bonobo/MonikerContext
-      Running - Bonobo/RunningContext
+      <para>
+        Activation - Bonobo/MonikerContext
+      </para>
     </listitem>
+    <listitem>
+      <para>
+        Running - Bonobo/RunningContext
+      </para>
+    </listitem>
   </itemizedlist>
 </para>
 
@@ -50,6 +56,8 @@
 server processes exit cleanly when all their objects and
 derived objects are dead. To do this we can simply do the
 following:
+</para>
+<para>
   <example>
     <title>How to get a factory to quit when it is idle</title>
     <programlisting>
@@ -73,7 +81,8 @@
 }
     </programlisting>
   </example>
-
+</para>
+<para>
   Since this is a commonly used thing there is a helper to make this
 easier:
   <example>
@@ -82,7 +91,6 @@
 bonobo_running_context_auto_exit_unref (factory) 
     </programlisting>
   </example>
-
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
Index: doc/api/tmpl/bonobo-event-source.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-event-source.sgml,v
retrieving revision 1.4
diff -u -r1.4 bonobo-event-source.sgml
--- doc/api/tmpl/bonobo-event-source.sgml	2001/02/21 17:19:15	1.4
+++ doc/api/tmpl/bonobo-event-source.sgml	2001/02/22 17:34:08
@@ -6,7 +6,7 @@
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-An event source object is responsible for channeling the emmission
+An event source object is responsible for channeling the emission
 of signals on an object to the appropriate attached listeners.
 The API is extremely simple and allows implementations to notify
 their listeners of a new event occuring.
Index: doc/api/tmpl/bonobo-exception.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-exception.sgml,v
retrieving revision 1.4
diff -u -r1.4 bonobo-exception.sgml
--- doc/api/tmpl/bonobo-exception.sgml	2001/02/21 12:42:56	1.4
+++ doc/api/tmpl/bonobo-exception.sgml	2001/02/22 17:34:08
@@ -9,12 +9,12 @@
 This module contains some useful helper functions
 that can be used to set various exceptions inside your
 CORBA methods. It also contains code to map between
-complex CORBA_Environment exception's and helpful
+complex CORBA_Environment exceptions and helpful
 strings suitable for display to the user.
 </para>
 
 <para>
-Typicaly to test for exceptions the BONOBO_EX macro
+Typically to test for exceptions the BONOBO_EX macro
 is used thus:
   <example>
      <title>Bonobo exception trapping and reporting</title>
Index: doc/api/tmpl/bonobo-generic-factory.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-generic-factory.sgml,v
retrieving revision 1.7
diff -u -r1.7 bonobo-generic-factory.sgml
--- doc/api/tmpl/bonobo-generic-factory.sgml	2001/02/21 10:19:28	1.7
+++ doc/api/tmpl/bonobo-generic-factory.sgml	2001/02/22 17:34:08
@@ -9,14 +9,14 @@
 The vast majority of Bonobo objects are created by the
 #BonoboGenericFactory implementation. This provides a
 very simple C sugar wrapper of the GNOME::ObjectFactory
-IDL interface, used by Oaf to instantiate new objects.
+IDL interface, used by OAF to instantiate new objects.
 </para>
 
 <para>
 Most applications when they start up will register their
-Bonobo object factory with oaf, this can be done like this:
+Bonobo object factory with OAF, this can be done like this:
   <example>
-    <title>How to register a factory with Oaf</title>
+    <title>How to register a factory with OAF</title>
     <programlisting>
 BonoboGenericFactory *factory;
 
@@ -26,7 +26,7 @@
 bonobo_running_context_auto_exit_unref (BONOBO_OBJECT (factory));
     </programlisting>
   </example>
-  This registers the factory with Oaf, associated with your
+  This registers the factory with OAF, associated with your
 factory's OAFIID ( as specified in the installed .oaf file ).
 The running_context_auto_exit_unref function is used to ensure
 that the program exits the gtk main loop when all of the factory's
@@ -34,7 +34,7 @@
 </para>
 <para>
 When an object that is created by your factory is demanded from
-oaf the my_factory_function will be called:
+OAF the my_factory_function will be called:
   <example>
     <title>A simple factory</title>
     <programlisting>
@@ -50,22 +50,22 @@
 	if (!strcmp (object_id, "OAFIID:Bonobo_Sample_Clock"))
 		object = bonobo_clock_control_new ();
 	else
-		g_warning ("Unknown OAFIID");
+		g_warning ("Unknown OAFIID '%s'", object_id);
 
 	return object;
 }
      </programlisting>
   </example>
-  This will return the newly constructed object via Oaf to
+  This will return the newly constructed object via OAF to
 the Object requestor.
 </para>
 
 <para>
 The generic factory works in two modes, multi and plain,
-it is reccommended that the multi mode be used. Also, there
+it is recommended that the multi mode be used. Also, there
 is a macro that can be used for simple components to remove
 the burden of writing the main function and getting the
-initialization correct, see #BONOBO_OAF_FACTORY_MULTI
+initialization correct, see #BONOBO_OAF_FACTORY_MULTI.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
Index: doc/api/tmpl/bonobo-listener.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-listener.sgml,v
retrieving revision 1.4
diff -u -r1.4 bonobo-listener.sgml
--- doc/api/tmpl/bonobo-listener.sgml	2001/02/21 04:32:50	1.4
+++ doc/api/tmpl/bonobo-listener.sgml	2001/02/22 17:34:08
@@ -7,7 +7,7 @@
 <!-- ##### SECTION Long_Description ##### -->
 <para>
    The BonoboListener object is a CORBA server used to receive events
-   emmited by a remote Bonobo::EventSource server.  The combination
+   emitted by a remote Bonobo::EventSource server.  The combination
    EventSource/Listener is used to notify one or more client
    applications of events that happen in a component.    Think of the
    EventSource/Listener as a notification/callback system that allows
@@ -36,7 +36,6 @@
 
     <informalexample>
       <programlisting>
-
 BonoboListener *keyboard_listener;
 
 my_listener_function (BonoboListener *l, char *event_name,
@@ -136,7 +135,7 @@
 </para>
 
 @listener: a pointer to the BonoboListener.
- event_name: the event name that was emmited.
+ event_name: the event name that was emitted.
 @any: The value (A CORBA Any) that was passed by the EventSource.
 @ev: Environment for returning CORBA errors.
 @user_data: the data pointer specified when you called bonobo_listener_new
Index: doc/api/tmpl/bonobo-moniker-util.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-moniker-util.sgml,v
retrieving revision 1.6
diff -u -r1.6 bonobo-moniker-util.sgml
--- doc/api/tmpl/bonobo-moniker-util.sgml	2001/02/21 12:42:56	1.6
+++ doc/api/tmpl/bonobo-moniker-util.sgml	2001/02/22 17:34:08
@@ -6,7 +6,7 @@
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The moniker utility functions provide two sets of functions
+The moniker utility functions provide two sets of functions:
   <itemizedlist>
     <listitem>
       <para>
@@ -42,7 +42,7 @@
 	Bonobo_Control control;
 	CORBA_Environment ev;
 
-	CORBA_exception_init (&ev);
+	CORBA_exception_init (&amp;ev);
 
 	control = bonobo_get_object ("file:/demo/a.jpeg",
                                      "Bonobo/Control", NULL);
Index: doc/api/tmpl/bonobo-property-bag-client.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-property-bag-client.sgml,v
retrieving revision 1.4
diff -u -r1.4 bonobo-property-bag-client.sgml
--- doc/api/tmpl/bonobo-property-bag-client.sgml	2001/02/21 10:19:28	1.4
+++ doc/api/tmpl/bonobo-property-bag-client.sgml	2001/02/22 17:34:08
@@ -16,7 +16,7 @@
 With the property bag interface, as in all current remote Bonobo
 method invocations, translation issues are very dodgy. Assuming
 that the server process was activated in the correct locale, all
-should be well, however there is no garentee that ( in a rapidly
+should be well, however there is no guarantee that ( in a rapidly
 changing locale environment ) the string will be correctly translated.
 It is difficult to know how to solve this problem.
 </para>
Index: doc/api/tmpl/bonobo-property-bag-xml.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-property-bag-xml.sgml,v
retrieving revision 1.3
diff -u -r1.3 bonobo-property-bag-xml.sgml
--- doc/api/tmpl/bonobo-property-bag-xml.sgml	2001/02/21 10:19:28	1.3
+++ doc/api/tmpl/bonobo-property-bag-xml.sgml	2001/02/22 17:34:08
@@ -6,14 +6,14 @@
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-This API is really super simple, it is designed in conjuction
+This API is really super simple. It is designed in conjuction
 with the #BonoboUINode API to allow you to serialize a #BonoboArg
 ( in fact a CORBA_any ) to an XML format, and obviously the
 converse.
 </para>
 
 <para>
-Here is a sample use in code to produce an XML string from a
+Here is a code sample to produce an XML string from a
 CORBA_any or BonoboArg:
    <example>
      <title>Converting Any to XML</title>
@@ -25,16 +25,16 @@
 	BonoboUINode     *node;
 	char             *value;
 
-	CORBA_exception_init (&ev);
+	CORBA_exception_init (&amp;ev);
 
-	node = bonobo_property_bag_xml_encode_any (NULL, bonobo_arg, &ev);
+	node = bonobo_property_bag_xml_encode_any (NULL, bonobo_arg, &amp;ev);
 	if (!node)
 		return NULL;
 
-	value = bonobo_property_bag_xml_decode_any (node, &ev);
+	value = bonobo_property_bag_xml_decode_any (node, &amp;ev);
 	bonobo_ui_node_free (node);
 
-	CORBA_exception_free (&ev);
+	CORBA_exception_free (&amp;ev);
 
 	return value;
 }
@@ -52,17 +52,18 @@
 {
 	CORBA_Environment ev;
 	BonoboUINode     *node;
+	BonoboArg        *value;
 
-	CORBA_exception_init (&ev);
+	CORBA_exception_init (&amp;ev);
 
 	node = bonobo_ui_node_from_string (xml);
 	if (!node)
 		return NULL;
 
-	value = bonobo_property_bag_xml_decode_any (node, &ev);
+	value = bonobo_property_bag_xml_decode_any (node, &amp;ev);
 
 	bonobo_ui_node_free (node);
-	CORBA_exception_free (&ev);
+	CORBA_exception_free (&amp;ev);
 
 	return value;
 }
Index: doc/api/tmpl/bonobo-property-bag.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-property-bag.sgml,v
retrieving revision 1.6
diff -u -r1.6 bonobo-property-bag.sgml
--- doc/api/tmpl/bonobo-property-bag.sgml	2001/02/21 17:19:15	1.6
+++ doc/api/tmpl/bonobo-property-bag.sgml	2001/02/22 17:34:08
@@ -24,7 +24,7 @@
 </para>
 
 <para>
-Here is a simple example use of the property bag
+Here is a simple example use of the property bag:
   <example>
      <title>Callbacks</title>
      <programlisting>
@@ -89,6 +89,8 @@
 }
      </programlisting>
   </example>
+</para>
+<para>
 Then to instantiate the property bag interface and associate it with
 a control perhaps we do:
   <example>
@@ -112,7 +114,7 @@
 	bonobo_object_unref (BONOBO_OBJECT (pb));
      </programlisting>
   </example>
-And finaly we need to notify listeners of changes in various properties
+And finally we need to notify listeners of changes in various properties
 so we could perhaps do:
   <example>
      <title></title>
Index: doc/api/tmpl/bonobo-transient.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-transient.sgml,v
retrieving revision 1.6
diff -u -r1.6 bonobo-transient.sgml
--- doc/api/tmpl/bonobo-transient.sgml	2001/02/21 00:22:01	1.6
+++ doc/api/tmpl/bonobo-transient.sgml	2001/02/22 17:34:08
@@ -149,11 +149,11 @@
  
 <para>
    The previous example shows: how the
-   <variable>my_transient</variable> object is first created, and how
+   <parameter>my_transient</parameter> object is first created, and what
    the implementations for the create_servant and destroy_servant look
    like.  It does not make use of the user pointer, so it passes
-   NULL.  But applications will most likely want to pass data here to
-   the new_servant and destroy_servant methods.  
+   NULL.  However, in practice, applications will most likely want to
+   pass data here to the new_servant and destroy_servant methods.  
 </para>
 
 <para>
Index: doc/api/tmpl/bonobo-xobject.sgml
===================================================================
RCS file: /cvs/gnome/bonobo/doc/api/tmpl/bonobo-xobject.sgml,v
retrieving revision 1.3
diff -u -r1.3 bonobo-xobject.sgml
--- doc/api/tmpl/bonobo-xobject.sgml	2001/02/21 17:19:15	1.3
+++ doc/api/tmpl/bonobo-xobject.sgml	2001/02/22 17:34:08
@@ -7,9 +7,9 @@
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 The BonoboXObject provides a backwards compatible, but easy to
-use way of writing CORBA servers. It drasticaly simplifies the
+use way of writing CORBA servers. It drastically simplifies the
 issues of epv and vepv construction by automating these, and
-automaticaly instantiates a CORBA_Object on gtk_type_new. This
+automatically instantiates a CORBA_Object on gtk_type_new. This
 removes clutter from construction time.
 </para>
 
@@ -41,7 +41,7 @@
 </para>
 
 <para>
-Then we setup the type using the <function>bonobo_x_type_unique</function>
+Then we set up the type using the <function>bonobo_x_type_unique</function>
 function instead of gtk_type_unique ( but otherwise in the standard Gtk+
 fashion ).
   <example>
@@ -66,7 +66,7 @@
 		type = bonobo_x_type_unique (ptype,
 			POA_Bonobo_Control__init, NULL,
 			GTK_STRUCT_OFFSET (BonoboControlClass, epv),
-			&info);
+			&amp;info);
 	}
 	return type;
 }
@@ -82,16 +82,17 @@
      </programlisting>
   </example>
 
-  The POA_Bonobo_Control__init is used to construct the CORBA object
+  The POA_Bonobo_Control__init function is used to construct the CORBA object
 and the GTK_STRUCT_OFFSET tells Bonobo where your epv structure is
 in the Class data, so it can build your epv for you.
-  The fini_fn is not used in ORBit, so it is faster to use NULL here.
+  The fini_fn function is not used in ORBit, so it is faster to use NULL here.
 </para>
 <para>
-Having registered the type in the class initialization function it
-is neccessary to fill out the epv with our entry points. NB. it may
-also be neccessary to override the parent's epv's, this can be done
-by accessing the class's parent's epv pointer.
+After registering the type in the class initialization function, we
+must fill out the epv with our entry points, similar to the way we
+hook up virtual class functions. It may also be necessary to override
+the parent's epv's; this can be done by accessing the epv pointer for
+the parent class.
   <example>
      <title>Setting up the class' methods</title>
      <programlisting>
@@ -99,7 +100,7 @@
 bonobo_control_class_init (BonoboControlClass *klass)
 {
 	GtkObjectClass *object_class = (GtkObjectClass *)klass;
-	POA_Bonobo_Control__epv *epv = &klass->epv;
+	POA_Bonobo_Control__epv *epv = &amp;klass->epv;
 
 	bonobo_control_parent_class = gtk_type_class (PARENT_TYPE);

References:
- Bonobo Docs Cleanup
  - From: John R. Sheets

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