some GLib and Atk stuff

svn path=/trunk/gtk-sharp/; revision=31529

doc/ChangeLog

@@ -1,3 +1,7 @@
+2004-07-27  John Luke  <john.luke@gmail.com>
+
+	some GLib and Atk docs
+
 2004-07-21  John Luke  <jluke@cfl.rr.com>
 
 	* en/Gtk/TextView.xml:

doc/en/Atk/Document.xml

@@ -10,8 +10,8 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>The interface which allows access to a DOM associated with on object.</summary>
-    <remarks>To be added</remarks>
+    <remarks>The <see cref="T:Atk.Document" /> interface should be supported by any object that has an associated document object model (DOM). This interface provides the standard mechanism allowing an assistive technology access to the DOM.</remarks>
   </Docs>
   <Base />
   <Interfaces>
@@ -28,9 +28,9 @@
         <ReturnType>System.IntPtr</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Gets a pointer that points to an instance of the DOM.</summary>
-        <returns>To be added: an object of type 'IntPtr'</returns>
+        <returns> a pointer to an instance of the DOM.</returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
     <Member MemberName="DocumentType">
@@ -40,9 +40,9 @@
         <ReturnType>System.String</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Gets a string indicating the document type.</summary>
-        <returns>To be added: an object of type 'string'</returns>
+        <returns> a string indicating the document type</returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
   </Members>

doc/en/Atk/Hypertext.xml

@@ -10,8 +10,9 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>The interface which provides standard mechanism for manipulating hyperlinks.
-    <remarks>To be added</remarks>
+</summary>
+    <remarks />
   </Docs>
   <Base />
   <Interfaces>
@@ -31,10 +32,10 @@
         <Parameter Name="char_index" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>The index into the array of hyperlinks that is associated with the character specified by <paramref name="char_index" />, or -1 if there is no hyperlink associated with this character.</summary>
-        <param name="char_index">To be added: an object of type 'int'</param>
+        <param name="char_index"> a character index</param>
-        <returns>To be added: an object of type 'int'</returns>
+        <returns> an index into the array of hyperlinks in hypertext</returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
     <Member MemberName="GetLink">
@@ -47,10 +48,10 @@
         <Parameter Name="link_index" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>The link in this hypertext document at index <paramref name="link_index" /></summary>
-        <param name="link_index">To be added: an object of type 'int'</param>
+        <param name="link_index"> an integer specifying the desired link</param>
-        <returns>To be added: an object of type 'Atk.Hyperlink'</returns>
+        <returns> the link in this hypertext document at index <paramref name="link_index" /></returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
     <Member MemberName="NLinks">
@@ -60,9 +61,9 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added</summary>
+        <summary>The number of links within this hypertext document.</summary>
-        <returns>To be added: an object of type 'int'</returns>
+        <returns>The number of links within this hypertext document.</returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
   </Members>

doc/en/Atk/StreamableContent.xml

@@ -10,8 +10,8 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>The interface which provides access to streamable content.</summary>
-    <remarks>To be added</remarks>
+    <remarks />
   </Docs>
   <Base />
   <Interfaces>
@@ -31,10 +31,10 @@
         <Parameter Name="i" Type="System.Int32" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>The string of the specified mime type.</summary>
-        <param name="i">To be added: an object of type 'int'</param>
+        <param name="i"> an int representing the position of the mime type starting from 0</param>
-        <returns>To be added: an object of type 'string'</returns>
+        <returns>a string representing the specified mime type</returns>
-        <remarks>To be added</remarks>
+        <remarks>The first mime type is at position 0, the second at position 1, and so on.</remarks>
       </Docs>
     </Member>
     <Member MemberName="NMimeTypes">
@@ -44,9 +44,9 @@
         <ReturnType>System.Int32</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added</summary>
+        <summary>The number of mime types supported by this object.</summary>
-        <returns>To be added: an object of type 'int'</returns>
+        <returns>the number of mime types supported by the object.</returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
   </Members>

doc/en/Atk/Table.xml

@@ -10,8 +10,18 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>The interface implemented for UI components which contain tabular or row/column information.</summary>
-    <remarks>To be added</remarks>
+    <remarks>
+      <para>
+        <see cref="T:Atk.Table" /> should be implemented by components which present elements ordered via rows and columns. It may also be used to present tree-structured information if the nodes of the trees can be said to contain multiple "columns". Individual elements of an <see cref="T:Atk.Table" /> are typically referred to as "cells", and these cells are exposed by <see cref="T:Atk.Table" /> as child <see cref="T:Atk.Object" />s of the <see cref="T:Atk.Table" />. Both row/column and child-index-based access to these children is provided.
+</para>
+      <para>
+Children of <see cref="T:Atk.Table" /> are frequently "lightweight" objects, that is, they may not have backing widgets in the host UI toolkit. They are therefore often transient.
+</para>
+      <para>
+Since tables are often very complex, <see cref="T:Atk.Table" /> includes provision for offering simplified summary information, as well as row and column headers and captions. Headers and captions are <see cref="T:Atk.Object" />s which may implement other interfaces (<see cref="T:Atk.Text" />, <see cref="T:Atk.Image" />, etc.) as appropriate. <see cref="T:Atk.Table" /> summaries may themselves be (simplified) <see cref="T:Atk.Table" />s, etc. 
+</para>
+    </remarks>
   </Docs>
   <Base />
   <Interfaces>

doc/en/Atk/Text.xml

@@ -10,8 +10,15 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>The interface implemented by components with text content.</summary>
-    <remarks>To be added</remarks>
+    <remarks>
+      <para>
+        <see cref="T:Atk.Text" /> should be implemented by <see cref="T:Atk.Object" />s on behalf of widgets that have text content which is either attributed or otherwise non-trivial. <see cref="T:Atk.Object" />s whose text content is simple, unattributed, and very brief may expose that content via atk_object_get_name instead; however if the text is editable, multi-line, typically longer than three or four words, attributed, selectable, or if the object already uses the 'name' ATK property for other information, the <see cref="T:Atk.Text" /> interface should be used to expose the text content. In the case of editable text content, <see cref="T:Atk.EditableText" /> (a subtype of the <see cref="T:Atk.Text" /> interface) should be implemented instead.
+</para>
+      <para>
+        <see cref="T:Atk.Text" /> provides not only traversal facilities and change notification for text content, but also caret tracking and glyph bounding box calculations. Note that the text strings are exposed as UTF-8, and are therefore potentially multi-byte, and caret-to-byte offset mapping makes no assumptions about the character length; also bounding box glyph-to-offset mapping may be complex for languages which use ligatures. 
+</para>
+    </remarks>
   </Docs>
   <Base />
   <Interfaces>

doc/en/Atk/Util.xml

@@ -10,8 +10,8 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>This is a utility class which supports the adding and removal of event listeners.</summary>
-    <remarks>To be added</remarks>
+    <remarks> The adding and removing of the listeners must be done in the same thread. The file also contains a number of utility functions.</remarks>
   </Docs>
   <Base>
     <BaseTypeName>GLib.Object</BaseTypeName>

doc/en/Atk/Value.xml

@@ -10,8 +10,10 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>The interface implemented by valuators and components which display or select a value from a bounded range of values.
-    <remarks>To be added</remarks>
+</summary>
+    <remarks>
+      <see cref="T:Atk.Value" /> should be implemented for components which either display a value from a bounded range, or which allow the user to specify a value from a bounded range, or both. For instance, most sliders and range controls, as well as dials, should have <see cref="T:Atk.Object" /> representations which implement <see cref="T:Atk.Value" /> on the component's behalf. <see cref="T:Atk.Value" />s may be read-only, in which case attempts to alter the value return <see langword="false" /> to indicate failure.</remarks>
   </Docs>
   <Base />
   <Interfaces>

doc/en/GLib/MainContext.xml

@@ -10,8 +10,8 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>Manages events in the main context.</summary>
-    <remarks>To be added</remarks>
+    <remarks />
   </Docs>
   <Base>
     <BaseTypeName>System.Object</BaseTypeName>
@@ -27,9 +27,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Checks if any sources have pending events for the given context.</summary>
         <returns>an object of type <see cref="T:System.Boolean" /></returns>
-        <remarks>To be added</remarks>
+        <remarks />
       </Docs>
     </Member>
     <Member MemberName="Iteration">
@@ -42,10 +42,10 @@
         <Parameter Name="MayBlock" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Runs a single iteration for the given main loop.</summary>
         <param name="MayBlock">an object of type <see cref="T:System.Boolean" /></param>
         <returns>an object of type <see cref="T:System.Boolean" /></returns>
-        <remarks>To be added</remarks>
+        <remarks>This involves checking to see if any event sources are ready to be processed, then if no events sources are ready and <paramref name="may_block" /> is <see langword="true" />, waiting for a source to become ready, then dispatching the highest priority events sources that are ready. Note that even when <paramref name="may_block" /> is <see langword="true" />, it is still possible for g_main_context_iteration() to return <see langword="false" />, since the the wait may be interrupted for other reasons than an event source becoming ready.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Iteration">
@@ -56,9 +56,9 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added</summary>
+        <summary>Runs a single iteration for the given main loop.</summary>
         <returns>an object of type <see cref="T:System.Boolean" /></returns>
-        <remarks>To be added</remarks>
+        <remarks>This is a convenience overload for <see cref="M:GLib.MainContext.Iteration(System.Boolean)" /> with <see langword="false" /> passed in.</remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">

doc/en/GLib/Markup.xml

@@ -10,8 +10,8 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the &lt;link location="node:gtk-sharp/programming/threads"&gt;Gtk# Thread Programming&lt;/link&gt; for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>Wrapper for glib markup</summary>
-    <remarks>To be added</remarks>
+    <remarks />
   </Docs>
   <Base>
     <BaseTypeName>System.Object</BaseTypeName>
@@ -29,10 +29,11 @@
         <Parameter Name="s" Type="System.String" />
       </Parameters>
       <Docs>
-        <summary>To be added</summary>
+        <summary>Escapes text so that the markup parser will parse it verbatim.</summary>
-        <param name="s">an object of type <see cref="T:System.String" /></param>
+        <param name="s">some valid Utf8 text</param>
-        <returns>an object of type <see cref="T:System.String" /></returns>
+        <returns>escaped text</returns>
-        <remarks>To be added</remarks>
+        <remarks>Less than, greater than, ampersand, etc. are replaced with the corresponding entities. This function would typically be used when writing out a file to be parsed with the markup parser.
+Note that this function does not protect whitespace and line endings from being processed according to the XML rules for normalization of line endings and attribute values.</remarks>
       </Docs>
     </Member>
   </Members>

doc/en/GLib/Object.xml

@@ -10,8 +10,8 @@
   </AssemblyInfo>
   <ThreadSafetyStatement>Gtk# is thread aware, but not thread safe; See the <link location="node:gtk-sharp/programming/threads">Gtk# Thread Programming</link> for details.</ThreadSafetyStatement>
   <Docs>
-    <summary>To be added</summary>
+    <summary>Base class for all of Gtk#.</summary>
-    <remarks>To be added</remarks>
+    <remarks />
   </Docs>
   <Base>
     <BaseTypeName>System.Object</BaseTypeName>