erts: Improve ref docs of atomics, counters and erlang

3 files changed, 18 insertions, 15 deletions

diff --git a/erts/doc/src/atomics.xml b/erts/doc/src/atomics.xml
index cf182da220..9439643a14 100644
--- a/erts/doc/src/atomics.xml
+++ b/erts/doc/src/atomics.xml
@@ -73,7 +73,9 @@
       <name name="new" arity="2" since="OTP 21.2"/>
       <fsummary>Create atomic array</fsummary>
       <desc>
-        <p>Create a new atomic array of <c><anno>Arity</anno></c> atomics.</p>
+        <p>Create a new array of <c><anno>Arity</anno></c>
+	number of atomics. All atomics in the array are initially set
+	to zero.</p>
 	<p>Argument <c><anno>Opts</anno></c> is a list of the following possible
 	options:</p>
 	<taglist>
diff --git a/erts/doc/src/counters.xml b/erts/doc/src/counters.xml
index 0c284393a9..fde4d75642 100644
--- a/erts/doc/src/counters.xml
+++ b/erts/doc/src/counters.xml
@@ -38,8 +38,7 @@
       <item>
 	<p>Counters wrap around at overflow and underflow operations.</p>
       </item>
-      <item><p>Counters are initialized to zero and can then only be written to
-        by adding or subtracting.</p>
+      <item><p>Counters are initialized to zero.</p>
       </item>
       <item>
 	<p>Write operations guarantee atomicity. No intermediate results can be
@@ -74,14 +73,16 @@
       <name name="new" arity="2" since="OTP 21.2"/>
       <fsummary>Create counter array</fsummary>
       <desc>
-        <p>Create a new counter array of <c><anno>Size</anno></c> counters.</p>
+        <p>Create a new counter array of <c><anno>Size</anno></c>
+	counters. All counters in the array are initially set to zero.</p>
 	<p>Argument <c><anno>Opts</anno></c> is a list of the following possible
 	options:</p>
 	<taglist>
 	  <tag><c>atomics</c> (Default)</tag>
 	  <item><p>Counters will be sequentially consistent. If write
-	  operation A is done sequentially before write operation B, then a concurrent reader
-	  may see none of them, only A, or both A and B. It cannot see only B.</p>
+	  operation A is done sequentially before write operation B,
+	  then a concurrent reader may see the result of none of them,
+	  only A, or both A and B. It cannot see the result of only B.</p>
 	  </item>
 	  <tag><c>write_concurrency</c></tag>
 	  <item><p>This is an optimization to achieve very efficient concurrent
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 67d7a07bae..ad9c107431 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -112,12 +112,12 @@
           <tag><c>microsecond</c></tag>
           <item>
             <p>Symbolic representation of the time unit
-              represented by the integer <c>1000000</c>.</p>
+              represented by the integer <c>1000_000</c>.</p>
           </item>
           <tag><c>nanosecond</c></tag>
           <item>
             <p>Symbolic representation of the time unit
-              represented by the integer <c>1000000000</c>.</p>
+              represented by the integer <c>1000_000_000</c>.</p>
           </item>
           <tag><c>native</c></tag>
           <item>
@@ -4486,7 +4486,7 @@ RealSystem = system + MissedSystem</code>
             driver of the port does not support this. For more
             information, see driver flag
             <seecref marker="driver_entry#driver_flags">
-            <c>![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]</c></seecref>.
+            <c>ERL_DRV_FLAG_SOFT_BUSY</c></seecref>.
           </item>
           <tag><c>nosuspend</c></tag>
           <item>The calling process is not suspended if the port is
@@ -5689,7 +5689,7 @@ RealSystem = system + MissedSystem</code>
         <p>Removes old code for <c><anno>Module</anno></c>.
           Before this BIF is used,
           <seemfa marker="#check_process_code/2">
-          <c>check_process_code/2</c></seemfa>is to be called to check
+          <c>check_process_code/2</c></seemfa> is to be called to check
           that no processes execute old code in the module.</p>
         <warning>
           <p>This BIF is intended for the code server (see
@@ -7772,7 +7772,7 @@ ok
             has been suspended
             more times by the calling process than can be represented by the
             currently used internal data structures. The system limit is
-            &gt; 2,000,000,000 suspends and will never be lower.
+            greater than 2 billion suspends and will never be lower.
           </item>
         </taglist>
       </desc>
@@ -10370,9 +10370,9 @@ hello
 <code type="none">
 timestamp() ->
     ErlangSystemTime = erlang:system_time(microsecond),
-    MegaSecs = ErlangSystemTime div 1000000000000,
-    Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
-    MicroSecs = ErlangSystemTime rem 1000000,
+    MegaSecs = ErlangSystemTime div 1000_000_000_000,
+    Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
+    MicroSecs = ErlangSystemTime rem 1000_000,
     {MegaSecs, Secs, MicroSecs}.</code>
         <p>It, however, uses a native implementation that does
           not build garbage on the heap and with slightly better
@@ -11905,7 +11905,7 @@ true</pre>
       <desc>
         <p>Voluntarily lets other processes (if any) get a chance to
           execute. Using this function is similar to
-          <c>receive after 1 -> ok end</c>, except that <c>yield()</c>
+          <c>receive after 1 -> true end</c>, except that <c>yield()</c>
           is faster.</p>
         <warning>
           <p>There is seldom or never any need to use this BIF