Merge branch 'siri/sasl/doc-editors/OTP-13000' into maint

* siri/sasl/doc-editors/OTP-13000:
  sasl: Editorial changes

1 files changed, 59 insertions, 65 deletions

diff --git a/lib/sasl/doc/src/overload.xml b/lib/sasl/doc/src/overload.xml
index 35877220ab..5c3d00afeb 100644
--- a/lib/sasl/doc/src/overload.xml
+++ b/lib/sasl/doc/src/overload.xml
@@ -35,98 +35,88 @@
   <module>overload</module>
   <modulesummary>An Overload Regulation Process</modulesummary>
   <description>
-    <p><c>overload</c> is a process which indirectly regulates CPU
+    <p><c>overload</c> is a process that indirectly regulates the CPU
       usage in the system. The idea is that a main application calls
-      the <c>request/0</c> function before starting a major job, and
+      function 
+      <seealso marker="#request/0"><c>request/0</c></seealso> 
+      before starting a major job and
       proceeds with the job if the return value is positive; otherwise
-      the job must not be started.
-      </p>
-    <p><c>overload</c> is part of the <c>sasl</c> application, and all
-      configuration parameters are defined there.
-      </p>
-    <p>A set of two intensities are maintained, the <c>total intensity</c> and the <c>accept intensity</c>. For that purpose
-      there are two configuration parameters, the <c>MaxIntensity</c>
-      and the <c>Weight</c> value (both are measured in 1/second).
-      </p>
+      the job must not be started.</p>
+    <p><c>overload</c> is part of the <c>SASL</c> application and all
+      configuration parameters are defined there.</p>
+    <p>A set of two intensities are maintained, the <c>total intensity</c>
+      and the <c>accept intensity</c>. For that purpose,
+      there are two configuration parameters, <c>MaxIntensity</c>
+      and <c>Weight</c>; both are measured in 1/second.</p>
     <p>Then total and accept intensities are calculated as
       follows. Assume that the time of the current call to
-      <c>request/0</c> is <c>T(n)</c>, and that the time of the
-      previous call was <c>T(n-1)</c>.
-      </p>
+      <c>request/0</c> is <c>T(n)</c> and that the time of the
+      previous call was <c>T(n-1)</c>.</p>
     <list type="bulleted">
       <item>
         <p>The current <c>total intensity</c>, denoted
-          <c>TI(n)</c>, is calculated according to the formula,
-          </p>
-        <p><c>TI(n) = exp(-Weight*(T(n) - T(n-1)) * TI(n-1) +  Weight</c>,
-          </p>
-        <p>where <c>TI(n-1)</c> is the previous total intensity.
-          </p>
+          <c>TI(n)</c>, is calculated according to the formula</p>
+        <p><c>TI(n) = exp(-Weight*(T(n) - T(n-1)) * TI(n-1) +  Weight</c>,</p>
+        <p>where <c>TI(n-1)</c> is the previous <c>total intensity</c>.</p>
       </item>
       <item>
         <p>The current <c>accept intensity</c>, denoted
-          <c>AI(n)</c>, is determined by the formula,
-          </p>
-        <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + Weight</c>,
-          </p>
-        <p>where <c>AI(n-1)</c> is the previous accept intensity,
-          provided that the value of <c>exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c> is less than <c>MaxIntensity</c>; otherwise the
-          value is
-          </p>
-        <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c>.
-          </p>
+          <c>AI(n)</c>, is determined by the formula</p>
+        <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + Weight</c>,</p>
+        <p>where <c>AI(n-1)</c> is the previous <c>accept intensity</c>,
+          if the value of <c>exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c>
+          is less than <c>MaxIntensity</c>. Otherwise the value is</p>
+        <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c></p>
       </item>
     </list>
     <p>The value of configuration parameter <c>Weight</c> controls the
-      speed with which the calculations of intensities will react to
+      speed with which the calculations of intensities react to
       changes in the underlying input intensity. The inverted value of
-      <c>Weight</c>,
-      </p>
-    <p><c>T = 1/Weight</c></p>
-    <p>can be thought of as the "time constant"
-      of the intensity calculation formulas. For example, if <c>Weight = 0.1</c>, then a change in the underlying input intensity will be
-      reflected in the <c>total</c> and <c>accept intensities</c> within
-      approximately 10 seconds.
-      </p>
+      <c>Weight</c>, <c>T = 1/Weight</c>, can be thought of as the
+      "time constant" of the intensity calculation formulas. For example,
+      if <c>Weight = 0.1</c>, a change in the underlying input intensity is
+      reflected in <c>total intensity</c> and <c>accept intensity</c> within
+      about 10 seconds.</p>
     <p>The overload process defines one alarm, which it sets using
-      <c>alarm_handler:set_alarm(Alarm)</c>.  <c>Alarm</c> is defined
-      as:
-      </p>
+      <c>alarm_handler:set_alarm(Alarm)</c>. <c>Alarm</c> is defined
+      as follows:</p>
     <taglist>
       <tag><c>{overload, []}</c></tag>
       <item>
-        <p>This alarm is set when the current accept intensity exceeds
-          <c>MaxIntensity</c>. 
-          </p>
+        <p>This alarm is set when the current <c>accept intensity</c> exceeds
+          <c>MaxIntensity</c>.</p>
       </item>
     </taglist>
-    <p>A new overload alarm is not set until the current accept
-      intensity has fallen below <c>MaxIntensity</c>. To prevent the
-      overload process from generating a lot of set/reset alarms, the
-      alarm is not reset until the current accept intensity has fallen
-      below 75% of <c>MaxIntensity</c>, and it is not until then that
-      the alarm can be set again.
-      </p>
+    <p>A new request is not accepted until the current <c>accept
+      intensity</c> has fallen below <c>MaxIntensity</c>. To prevent the
+      overload process from generating many set/reset alarms, the
+      alarm is not reset until the current <c>accept intensity</c> has fallen
+      below 75% of <c>MaxIntensity</c>; it is not until then that
+      the alarm can be set again.</p>
   </description>
+
   <funcs>
     <func>
       <name>request() -> accept | reject</name>
-      <fsummary>Request to proceed with current job</fsummary>
+      <fsummary>Requests to proceed with current job.</fsummary>
       <desc>
         <p>Returns <c>accept</c> or <c>reject</c> depending on the
-          current value of the accept intensity.  </p>
+          current value of the <c>accept intensity</c>.</p>
         <p>The application
-          calling this function should be processed with the job in
+          calling this function is to proceed with the job in
           question if the return value is <c>accept</c>; otherwise it
-          should not continue with that job.
-          </p>
+          is not to continue with that job.</p>
       </desc>
     </func>
+
     <func>
       <name>get_overload_info() -> OverloadInfo</name>
-      <fsummary>Return current overload information data</fsummary>
+      <fsummary>Returns current overload information data.</fsummary>
       <type>
-        <v>OverloadInfo = [{total_intensity, TotalIntensity}, {accept_intensity, AcceptIntensity}, {max_intensity, MaxIntensity}, {weight, Weight}, {total_requests, TotalRequests}, {accepted_requests, AcceptedRequests}].</v>
+        <v>OverloadInfo = [{total_intensity, TotalIntensity},
+          {accept_intensity, AcceptIntensity}, {max_intensity,
+          MaxIntensity}, {weight, Weight}, {total_requests,
+          TotalRequests}, {accepted_requests, AcceptedRequests}].</v>
         <v>TotalIntensity = float() > 0</v>
         <v>AcceptIntensity = float() > 0</v>
         <v>MaxIntensity = float() > 0</v>
@@ -135,18 +125,22 @@
         <v>AcceptedRequests = integer()</v>
       </type>
       <desc>
-        <p>Returns the current total and accept intensities, the
-          configuration parameters, and absolute counts of the total
-          number of requests, and accepted number of requests (since
-          the overload process was started).</p>
+        <p>Returns:</p>
+        <list type="bulleted">
+          <item>Current total and accept intensities</item>
+          <item>Configuration parameters</item>
+          <item>Absolute counts of the total number of requests</item>
+          <item>Accepted number of requests (since the overload
+            process was started)</item>
+        </list>
       </desc>
     </func>
   </funcs>
 
   <section>
     <title>See Also</title>
-    <p>alarm_handler(3), sasl(3)
-      </p>
+    <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>,
+      <seealso marker="sasl_app"><c>sasl(6)</c></seealso></p>
   </section>
 </erlref>