Update asn1 documentation

Language cleaned up by the technical writer xsipewe from Combitech.
Proofreading and and additional corrections by Björn Gustavsson
and Dan Gudmundsson.

1 files changed, 45 insertions, 46 deletions

diff --git a/lib/mnesia/doc/src/mnesia_frag_hash.xml b/lib/mnesia/doc/src/mnesia_frag_hash.xml
index 0d660925e7..fe6d847655 100644
--- a/lib/mnesia/doc/src/mnesia_frag_hash.xml
+++ b/lib/mnesia/doc/src/mnesia_frag_hash.xml
@@ -34,22 +34,23 @@
     <file>mnesia_frag_hash.sgml</file>
   </header>
   <module>mnesia_frag_hash</module>
-  <modulesummary>Defines mnesia_frag_hash callback behaviour</modulesummary>
+  <modulesummary>Defines mnesia_frag_hash callback behavior</modulesummary>
   <description>
-    <p>The module <c>mnesia_frag_hash</c> defines a callback
-      behaviour for user defined hash functions of fragmented tables.</p>
+    <p>This module defines a callback behavior for user-defined hash
+      functions of fragmented tables.</p>
     <p>Which module that is selected to implement the <c>mnesia_frag_hash</c>
-      behaviour for a particular fragmented table is specified together
+      behavior for a particular fragmented table is specified together
       with the other <c>frag_properties</c>. The <c>hash_module</c> defines
       the module name. The <c>hash_state</c> defines the initial hash state.</p>
-    <p>It implements dynamic hashing which is a kind of hashing
+    <p>This module implements dynamic hashing, which is a kind of hashing
       that grows nicely when new fragments are added. It is well
-      suited for scalable hash tables</p>
+      suited for scalable hash tables.</p>
   </description>
+
   <funcs>
     <func>
       <name>init_state(Tab, State) -> NewState | abort(Reason)</name>
-      <fsummary>Initiate the hash state for a new table</fsummary>
+      <fsummary>Initiates the hash state for a new table.</fsummary>
       <type>
         <v>Tab = atom()</v>
         <v>State = term()</v>
@@ -57,21 +58,21 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>This function is invoked when a fragmented table is
-          created with <c>mnesia:create_table/2</c> or when a
-          normal (un-fragmented) table is converted to be a
+        <p>Starts when a fragmented table is
+          created with the function <c>mnesia:create_table/2</c> or
+          when a normal (unfragmented) table is converted to be a
           fragmented table with <c>mnesia:change_table_frag/2</c>.</p>
-        <p>Note that the <c>add_frag/2</c> function will be invoked
-          one time each for the rest of the fragments (all but number 1)
+        <p>Notice that the function <c>add_frag/2</c> is started
+          one time for each of the other fragments (except number 1)
           as a part of the table creation procedure.</p>
-        <p><c>State</c> is the initial value of the <c>hash_state</c> <c>frag_property</c>. The <c>NewState</c> will be stored as
-          <c>hash_state</c> among the other <c>frag_properties</c>.
-          </p>
+        <p><c>State</c> is the initial value of the <c>hash_state</c>
+          <c>frag_property</c>. <c>NewState</c> is stored as
+          <c>hash_state</c> among the other <c>frag_properties</c>.</p>
       </desc>
     </func>
     <func>
       <name>add_frag(State) -> {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)</name>
-      <fsummary>This function is invoked when a new fragment is added to a fragmented table</fsummary>
+      <fsummary>Starts when a new fragment is added to a fragmented table.</fsummary>
       <type>
         <v>State = term()</v>
         <v>NewState = term()</v>
@@ -80,27 +81,26 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>In order to scale well, it is a good idea ensure that the
-          records are evenly distributed over all fragments including
+        <p>To scale well, it is a good idea to ensure that the
+          records are evenly distributed over all fragments, including
           the new one.</p>
-        <p>The <c>NewState</c> will be stored as <c>hash_state</c> among the
-          other <c>frag_properties</c>. 
-          </p>
-        <p>As a part of the <c>add_frag</c> procedure, Mnesia will iterate
+        <p><c>NewState</c> is stored as <c>hash_state</c> among the
+          other <c>frag_properties</c>.</p>
+        <p>As a part of the <c>add_frag</c> procedure, <c>Mnesia</c> iterates
           over all fragments corresponding to the <c>IterFrags</c> numbers
-          and invoke <c>key_to_frag_number(NewState,RecordKey)</c> for
+          and starts <c>key_to_frag_number(NewState,RecordKey)</c> for
           each record. If the new fragment differs from the old
-          fragment, the record will be moved to the new fragment.</p>
+          fragment, the record is moved to the new fragment.</p>
         <p>As the <c>add_frag</c> procedure is a part of a schema
-          transaction Mnesia will acquire a write locks on the
-          affected tables. That is both the fragments corresponding
+          transaction, <c>Mnesia</c> acquires write locks on the
+          affected tables. That is, both the fragments corresponding
           to <c>IterFrags</c> and those corresponding to
           <c>AdditionalLockFrags</c>.</p>
       </desc>
     </func>
     <func>
       <name>del_frag(State) ->  {NewState, IterFrags, AdditionalLockFrags} | abort(Reason)</name>
-      <fsummary>This function is invoked when a fragment is deleted from a fragmented table</fsummary>
+      <fsummary>Starts when a fragment is deleted from a fragmented table.</fsummary>
       <type>
         <v>State = term()</v>
         <v>NewState = term()</v>
@@ -109,39 +109,38 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>The <c>NewState</c> will be stored as <c>hash_state</c> among the
-          other <c>frag_properties</c>. 
-          </p>
-        <p>As a part of the <c>del_frag</c> procedure, Mnesia will iterate
+        <p><c>NewState</c> is stored as <c>hash_state</c> among the
+          other <c>frag_properties</c>.</p>
+        <p>As a part of the <c>del_frag</c> procedure, <c>Mnesia</c> iterates
           over all fragments corresponding to the <c>IterFrags</c> numbers
-          and invoke <c>key_to_frag_number(NewState,RecordKey)</c> for
+          and starts <c>key_to_frag_number(NewState,RecordKey)</c> for
           each record. If the new fragment differs from the old
-          fragment, the record will be moved to the new fragment.</p>
-        <p>Note that all records in the last fragment must be moved to
-          another fragment as the entire fragment will be deleted.</p>
+          fragment, the record is moved to the new fragment.</p>
+        <p>Notice that all records in the last fragment must be moved to
+          another fragment, as the entire fragment is deleted.</p>
         <p>As the <c>del_frag</c> procedure is a part of a schema
-          transaction Mnesia will acquire a write locks on the
-          affected tables. That is both the fragments corresponding
+          transaction, <c>Mnesia</c> acquires write locks on the
+          affected tables. That is, both the fragments corresponding
           to <c>IterFrags</c> and those corresponding to
           <c>AdditionalLockFrags</c>.</p>
       </desc>
     </func>
     <func>
       <name>key_to_frag_number(State, Key) -> FragNum | abort(Reason)</name>
-      <fsummary>Resolves the key of a record into a fragment number</fsummary>
+      <fsummary>Resolves the key of a record into a fragment number.</fsummary>
       <type>
         <v>FragNum = integer()()</v>
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>This function is invoked whenever Mnesia needs to determine
+        <p>Starts whenever <c>Mnesia</c> needs to determine
           which fragment a certain record belongs to. It is typically
-          invoked at read, write and delete.</p>
+          started at <c>read</c>, <c>write</c>, and <c>delete</c>.</p>
       </desc>
     </func>
     <func>
       <name>match_spec_to_frag_numbers(State, MatchSpec) -> FragNums | abort(Reason)</name>
-      <fsummary>Resolves a MatchSpec into a list of fragment numbers</fsummary>
+      <fsummary>Resolves a <c>MatchSpec</c> into a list of fragment numbers.</fsummary>
       <type>
         <v>MatcSpec = ets_select_match_spec()</v>
         <v>FragNums = [FragNum]</v>
@@ -149,17 +148,17 @@
         <v>Reason = term()</v>
       </type>
       <desc>
-        <p>This function is invoked whenever Mnesia needs to determine
-          which fragments that needs to be searched for a MatchSpec.
-          It is typically invoked at select and match_object.</p>
+        <p>This function is called whenever <c>Mnesia</c> needs to determine
+          which fragments that need to be searched for a <c>MatchSpec</c>.
+          It is typically called by <c>select</c> and
+          <c>match_object</c>.</p>
       </desc>
     </func>
   </funcs>
 
   <section>
     <title>See Also</title>
-    <p>mnesia(3)
-      </p>
+    <p><seealso marker="mnesia:mnesia">mnesia(3)</seealso></p>
   </section>
   
 </erlref>