API comment fixes



This patch brings a handful of IDL and C API comments up to date, plus
a couple grammar fixes.

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.956
diff -u -r1.956 ChangeLog
--- ChangeLog	2001/02/09 18:10:41	1.956
+++ ChangeLog	2001/02/13 21:53:31
@@ -1,3 +1,21 @@
+2001-02-13  John R. Sheets  <dusk ravendusk org>
+
+	* bonobo/bonobo-object-client.c: 
+	* bonobo/bonobo-moniker.c:
+	* bonobo/bonobo-object.c:
+	* bonobo/bonobo-ui-component.h:
+	* gshell/README:
+	* idl/Bonobo_Context.idl:
+	* idl/Bonobo_Control.idl:
+	* idl/Bonobo_Embeddable.idl:
+	* idl/Bonobo_Listener.idl:
+	* idl/Bonobo_Persist.idl:
+	* idl/Bonobo_Progressive.idl:
+	* idl/Bonobo_Property.idl:
+	* idl/Bonobo_Storage.idl:
+	* idl/Bonobo_Zoomable.idl: Minor tweaks in comments, update old
+	function and parameter names.
+
 2001-02-09  Cody Russell  <bratsche gnome org>
 	* bonobo/bonobo-ui-engine-config.c: Remove the Cancel button.
 	Since this dialog makes changes in real time, this button serves
Index: bonobo/bonobo-moniker.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-moniker.c,v
retrieving revision 1.45
diff -u -r1.45 bonobo-moniker.c
--- bonobo/bonobo-moniker.c	2001/02/08 23:37:42	1.45
+++ bonobo/bonobo-moniker.c	2001/02/13 21:41:16
@@ -144,10 +144,11 @@
  * bonobo_moniker_get_name_escaped:
  * @moniker: a moniker
  * 
- * Get the full; escaped display name of the moniker eg.
+ * Get the full, escaped display name of the moniker eg.
  * file:/tmp/hash\#.gz returns file:/tmp/hash\#.gz
  * 
- * Return value: the string.
+ * Return value: the dynamically allocated string.  
+ * Must release with g_free().
  **/
 char *
 bonobo_moniker_get_name_escaped (BonoboMoniker *moniker)
@@ -447,6 +448,7 @@
  * @corba_moniker: a CORBA handle inheriting from Bonobo::Moniker, or
  * CORBA_OBJECT_NIL, in which case a base Bonobo::Moniker is created.
  * @prefix: the prefix name of the moniker eg. 'file:', '!' or 'tar:' or NULL
+ * @shlib_id:
  * 
  *  Constructs a newly created bonobo moniker with the given arguments.
  * 
Index: bonobo/bonobo-object-client.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-object-client.c,v
retrieving revision 1.52
diff -u -r1.52 bonobo-object-client.c
--- bonobo/bonobo-object-client.c	2001/01/18 10:30:03	1.52
+++ bonobo/bonobo-object-client.c	2001/02/13 21:41:17
@@ -46,11 +46,11 @@
 /**
  * bonobo_object_activate:
  * @iid: an OAFIID
- * @flags: activation flags
+ * @oaf_flags: activation flags
  *
  * 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 trough the moniker system.
+ * which does object activation through the moniker system.
  * 
  * You might also consider doing property-based activation using the 
  * the OAF-based capabilities. 
@@ -114,7 +114,7 @@
 /**
  * bonobo_object_activate_async:
  * @iid: an OAFIID
- * @flags: activation flags
+ * @oaf_flags: activation flags
  * @callback: a callback function
  * @user_data: user data
  *
Index: bonobo/bonobo-object.c
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-object.c,v
retrieving revision 1.100
diff -u -r1.100 bonobo-object.c
--- bonobo/bonobo-object.c	2001/02/06 04:33:24	1.100
+++ bonobo/bonobo-object.c	2001/02/13 21:41:23
@@ -375,7 +375,7 @@
  * @object: a Bonobo_Unknown corba object
  * @ev: Corba_Environment
  * 
- *   This function returns a duplicated CORBA Object reference,
+ *   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.
@@ -413,9 +413,9 @@
  * @object: a Bonobo_Unknown corba object
  * @ev: Corba_Environment, optional
  * 
- *   This function returns releases a CORBA Object reference,
+ *   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
+ * This is the converse of bonobo_object_dup_ref. We
  * tolerate object == CORBA_OBJECT_NIL silently
  **/
 void
@@ -1103,7 +1103,7 @@
 }
 
 /**
- * bonobo_object_from_servant:
+ * bonobo_object_new_from_servant:
  * @servant: A Servant that implements the Bonobo::Unknown interface
  *
  * Returns: The servant @servant wrapped in a BonoboObject.
Index: bonobo/bonobo-ui-component.h
===================================================================
RCS file: /cvs/gnome/bonobo/bonobo/bonobo-ui-component.h,v
retrieving revision 1.23
diff -u -r1.23 bonobo-ui-component.h
--- bonobo/bonobo-ui-component.h	2001/02/06 04:33:24	1.23
+++ bonobo/bonobo-ui-component.h	2001/02/13 21:41:25
@@ -1,6 +1,6 @@
 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
 /**
- * gnome-component-ui.h: Client UI signal multiplexer and verb repository.
+ * bonobo-ui-component.h: Client UI signal multiplexer and verb repository.
  *
  * Author:
  *     Michael Meeks (michael helixcode com)
Index: gshell/README
===================================================================
RCS file: /cvs/gnome/bonobo/gshell/README,v
retrieving revision 1.1
diff -u -r1.1 README
--- gshell/README	1999/11/17 10:24:36	1.1
+++ gshell/README	2001/02/13 21:41:30
@@ -2,6 +2,6 @@
 ===================================
 
 The idea is to make gshell a generic container which provides an emacs like
-framework for bonobo components. Since bonobo components supports multiple
-views its easy to implement the emacs Buffer/Frame concept. It is also a good
+framework for bonobo components. Since bonobo components support multiple
+views it's easy to implement the emacs Buffer/Frame concept. It is also a good
 framework to test new components/features.
Index: idl/Bonobo_Context.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Context.idl,v
retrieving revision 1.8
diff -u -r1.8 Bonobo_Context.idl
--- idl/Bonobo_Context.idl	2001/01/25 20:01:15	1.8
+++ idl/Bonobo_Context.idl	2001/02/13 21:41:30
@@ -60,7 +60,7 @@
 	/*
 	 * RunningContext: a live object tracker.
 	 *
-	 *  This interface is aggregated with a EventSource that
+	 *  This interface is aggregated with an EventSource that
 	 * fires: 'bonobo:last_unref' when all objects are released.
 	 */
 	interface RunningContext : Unknown {
@@ -73,7 +73,7 @@
 		void addObject    (in Object object);
 
 		/**
-		 * addObject:
+		 * removeObject:
 		 * @object: an object about to be destroyed
 		 *
 		 * Removes an object from tracking.
Index: idl/Bonobo_Control.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Control.idl,v
retrieving revision 1.26
diff -u -r1.26 Bonobo_Control.idl
--- idl/Bonobo_Control.idl	2001/02/07 02:45:06	1.26
+++ idl/Bonobo_Control.idl	2001/02/13 21:41:32
@@ -37,8 +37,8 @@
 	 * queueResize:
 	 *
 	 * Tell the container that the Control would like to be
-	 * resized.  It should follow-up by calling
-	 * Control:size_request()
+	 * resized.  The container should follow-up by calling
+	 * Control::setSize ()
 	 *
 	 */
 	void queueResize ();
@@ -101,7 +101,7 @@
 	 * @id: An X Window ID.
 	 *
 	 *   Sets the window ID that should be used for the plug
-	 * of this window, the id encoding is is described above.
+	 * of this window, the id encoding is as described above.
 	 */
 	void setWindowId (in windowId id);
 
Index: idl/Bonobo_Embeddable.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Embeddable.idl,v
retrieving revision 1.35
diff -u -r1.35 Bonobo_Embeddable.idl
--- idl/Bonobo_Embeddable.idl	2001/01/25 20:01:15	1.35
+++ idl/Bonobo_Embeddable.idl	2001/02/13 21:41:32
@@ -52,7 +52,7 @@
 
 	/**
 	 * setClientSite:
-	 * @client_site: the client site for this Object
+	 * @clientSite: the client site for this Object
 	 *
 	 * Sets the client site for this object
 	 */
@@ -100,7 +100,7 @@
 
 	/**
 	 * advise:
-	 * @sink: Where can the object inform of state changes
+	 * @advise: Where can the object inform of state changes
 	 *
 	 * Sets the object AdviseSink to @advise.  This is used
 	 * to allow the Object to notify its container of any state
Index: idl/Bonobo_Listener.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Listener.idl,v
retrieving revision 1.11
diff -u -r1.11 Bonobo_Listener.idl
--- idl/Bonobo_Listener.idl	2001/01/25 20:01:15	1.11
+++ idl/Bonobo_Listener.idl	2001/02/13 21:41:33
@@ -33,7 +33,7 @@
 		exception UnknownListener {};
   
   		/**
- 		 * add_listener: Adds a listener to all events being
+ 		 * addListener: Adds a listener to all events being
  		 * emitted by this object.
   		 * @l: the listener implementation.
 		 *
@@ -43,10 +43,10 @@
  		ListenerId addListener (in Listener l);
   		
   		/**
- 		 * add_listener: Adds a listener to certain events
+ 		 * addListenerWithMask: Adds a listener to certain events
  		 * emitted by this object.
  		 * @l: the listener implementation.
- 		 * @mask: a comma-separated list of event names this listener 
+ 		 * @event_mask: a comma-separated list of event names this listener 
 		 * is interested in recieving. If this listener is already 
  		 * receiving events from this EventSource, only the 
  		 * events listed here will be delivered.
@@ -58,7 +58,7 @@
 						in string   event_mask);
  
  		/**
-  		 * remove_listener: Removes a listener
+  		 * removeListener: Removes a listener
   		 * @id: the listener Id
   		 */
  		void removeListener (in ListenerId id)
Index: idl/Bonobo_Persist.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Persist.idl,v
retrieving revision 1.24
diff -u -r1.24 Bonobo_Persist.idl
--- idl/Bonobo_Persist.idl	2001/01/25 20:01:15	1.24
+++ idl/Bonobo_Persist.idl	2001/02/13 21:41:33
@@ -174,7 +174,7 @@
 		 *
 		 * If no exception was thrown the data in the stream has
 		 * the requested content type; if no type was requested
-		 * the first entry from get_content_types is returned.
+		 * the first entry from getContentTypes is returned.
 		 * Hence no return value is needed.
 		 * 
 		 * Saves the state of the object to the @stream
Index: idl/Bonobo_Progressive.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Progressive.idl,v
retrieving revision 1.9
diff -u -r1.9 Bonobo_Progressive.idl
--- idl/Bonobo_Progressive.idl	2001/01/25 20:01:15	1.9
+++ idl/Bonobo_Progressive.idl	2001/02/13 21:41:34
@@ -28,7 +28,7 @@
 		 * start:
 		 *
 		 * This method signals that a new transmission of data
-		 * is coming in.  It must be called before add_data
+		 * is coming in.  It must be called before addData
 		 * can be used.
 		 */
 		void start ();
@@ -43,6 +43,7 @@
 
 		/**
 		 * addData:
+		 * @buffer:
 		 *
 		 * As each chunk of data comes in, this method is
 		 * called with a CORBA sequence buffer, which
@@ -52,6 +53,7 @@
 
 		/**
 		 * setSize:
+		 * @count:
 		 *
 		 * This method notifies a component of the total size
 		 * of the incoming data.  It can be called at any
Index: idl/Bonobo_Property.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Property.idl,v
retrieving revision 1.20
diff -u -r1.20 Bonobo_Property.idl
--- idl/Bonobo_Property.idl	2001/01/25 20:01:15	1.20
+++ idl/Bonobo_Property.idl	2001/02/13 21:41:35
@@ -42,7 +42,7 @@
 	 * Do not confuse this with the human-readable string which
 	 * should be presented to the user in a property editor.  A
 	 * property name is a human-language-independent key used to
-	 * identify a property.  See get_docstring() for more
+	 * identify a property.  See getDocString() for more
 	 * information about human-readable property descriptors.
 	 */
 	string getName ();
Index: idl/Bonobo_Storage.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Storage.idl,v
retrieving revision 1.29
diff -u -r1.29 Bonobo_Storage.idl
--- idl/Bonobo_Storage.idl	2001/01/25 20:01:15	1.29
+++ idl/Bonobo_Storage.idl	2001/02/13 21:41:36
@@ -57,6 +57,7 @@
 
 		/**
 		 * getInfo:
+		 * @mask:
 		 *
 		 * Returns a StorageInfo structure which contains
 		 * the name, content_type and size info.
@@ -66,6 +67,8 @@
 		
 		/**	
 		 * setInfo:
+		 * @info:
+		 * @mask:
 		 *
 		 */
 		void setInfo (in StorageInfo info, in StorageInfoFields mask)
@@ -109,7 +112,7 @@
 	
 		/**
 		 * copyTo:
-		 * @path: destination file.
+		 * @dest: destination file.
 		 * @bytes: number of bytes to copy, or -1 to copy until eof
 		 * @read: output, how many bytes were read.
 		 * @writen: output, how many bytes were written.
@@ -165,6 +168,8 @@
 
 		/**
 		 * getInfo:
+		 * @path:
+		 * @mask:
 		 *
 		 * Returns a StorageInfo structure which contains
 		 * the name, content_type and size info.
@@ -175,6 +180,9 @@
 		
 		/**	
 		 * setInfo:
+		 * @path:
+		 * @info:
+		 * @mask:
 		 *
 		 */
 		void setInfo (in string path, in StorageInfo info, 
@@ -215,6 +223,7 @@
 		/**
 		 * listContents:
 		 * @path: path that we want to examine.
+		 * @mask:
 		 *
 		 * Returns a list of all the Storage and Streams available
 		 * at @path.
Index: idl/Bonobo_Zoomable.idl
===================================================================
RCS file: /cvs/gnome/bonobo/idl/Bonobo_Zoomable.idl,v
retrieving revision 1.8
diff -u -r1.8 Bonobo_Zoomable.idl
--- idl/Bonobo_Zoomable.idl	2001/01/25 20:01:15	1.8
+++ idl/Bonobo_Zoomable.idl	2001/02/13 21:41:37
@@ -37,12 +37,11 @@
 	
 /* A zoomable has the responsibility to look for this
  * interface on its Bonobo control frame and call
- * zoom_level_changed whenever it changes the zoom level (on
+ * onLevelChanged whenever it changes the zoom level (on
  * its own or due to calls from the zoomable interface).
 */
 interface ZoomableFrame : ::Bonobo::Unknown {
 	/**
-	 *
 	 * onLevelChanged:
 	 * @zoom_level: The new zoom level.
 	 *
@@ -53,7 +52,6 @@
 	oneway void onLevelChanged (in float zoom_level);
 
 	/**
-	 *
 	 * onParametersChanged:
 	 *
 	 * Informs the ZoomableFrame that some of the zoom parameters
@@ -68,9 +66,7 @@
 	 * This is a read-only value and indicates the actual current
 	 * zoom level of the component. It is changed by the component
 	 * after successfully completing a zooming operation before
-	 * calling the `report_zoom_level_changed' method on its
-	 * ZoomableFrame.
-	 *
+	 * calling the `onLevelChanged' method on its ZoomableFrame.
 	 */
 	readonly attribute float level;
 
@@ -95,15 +91,14 @@
 	oneway void zoomDefault ();
 
 	/**
-	 *
 	 * setLevel:
 	 * @zoom_level: The new zoom level.
 	 *
 	 * Tells the component to zoom to @zoom_level.
 	 *
 	 * If the component only supports fixed zoom levels,
-	 * then the actual zoom level will be set to whatever
-	 * is closes possible to @zoom_level.
+	 * then the actual zoom level will be set to the
+	 * closest possible value of @zoom_level.
 	 */
 	void setLevel (in float zoom_level);
 


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