Merge branch 'hb/stdlib/doc_specs/OTP-9271' into dev

* hb/stdlib/doc_specs/OTP-9271:
  Use Erlang specs and types for documentation

Conflicts:
	lib/stdlib/doc/src/timer.xml

1 files changed, 106 insertions, 120 deletions

diff --git a/lib/stdlib/doc/src/calendar.xml b/lib/stdlib/doc/src/calendar.xml
index 075c7f9c78..4876b37127 100644
--- a/lib/stdlib/doc/src/calendar.xml
+++ b/lib/stdlib/doc/src/calendar.xml
@@ -73,100 +73,125 @@
       week number.</p>
   </description>
 
-  <section>
-    <title>DATA TYPES</title>
-    <code type="none">
-date() = {Year, Month, Day}
-  Year = int()
-  Month = 1..12
-  Day = 1..31
-Year cannot be abbreviated. Example: 93 denotes year 93, not 1993.
-Valid range depends on the underlying OS.
-The date tuple must denote a valid date.
+  <datatypes>
+    <datatype>
+      <name name="t_datetime"/>
+    </datatype>
+    <datatype>
+      <name name="t_datetime1970"/>
+    </datatype>
+    <datatype>
+      <name name="t_date"/>
+    </datatype>
+    <datatype>
+      <name name="year"/>
+      <desc><p>Year cannot be abbreviated. Example: 93 denotes year
+        93, not 1993. Valid range depends on the underlying OS. The
+        date tuple must denote a valid date.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="year1970"/>
+    </datatype>
+    <datatype>
+      <name name="month"/>
+    </datatype>
+    <datatype>
+      <name name="day"/>
+    </datatype>
+    <datatype>
+      <name name="t_time"/>
+    </datatype>
+    <datatype>
+      <name name="hour"/>
+    </datatype>
+    <datatype>
+      <name name="minute"/>
+    </datatype>
+    <datatype>
+      <name name="second"/>
+    </datatype>
+    <datatype>
+      <name name="daynum"/>
+    </datatype>
+    <datatype>
+      <name name="ldom"/>
+    </datatype>
+    <datatype>
+      <name name="t_now"/>
+      <desc><p>See <seealso marker="erts:erlang#now/0">erlang:now/0</seealso>.</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="t_yearweeknum"/>
+    </datatype>
+    <datatype>
+      <name name="weeknum"/>
+    </datatype>
+  </datatypes>
 
-time() = {Hour, Minute, Second}
-  Hour = 0..23
-  Minute = Second = 0..59</code>
-  </section>
   <funcs>
     <func>
-      <name>date_to_gregorian_days(Date) -> Days</name>
-      <name>date_to_gregorian_days(Year, Month, Day) -> Days</name>
+      <name name="date_to_gregorian_days" arity="1"/>
+      <name name="date_to_gregorian_days" arity="3"/>
+      <type variable="Date" name_i="1"/>
+      <type variable="Year"/>
+      <type variable="Month"/>
+      <type variable="Day"/>
       <fsummary>Compute the number of days from year 0 up to the given date</fsummary>
-      <type>
-        <v>Date = date()</v>
-        <v>Days = int()</v>
-      </type>
       <desc>
         <p>This function computes the number of gregorian days starting
           with year 0 and ending at the given date.</p>
       </desc>
     </func>
     <func>
-      <name>datetime_to_gregorian_seconds({Date, Time}) -> Seconds</name>
+      <name name="datetime_to_gregorian_seconds" arity="1"/>
       <fsummary>Compute the number of seconds from year 0 up to the given date and time</fsummary>
-      <type>
-        <v>Date = date()</v>
-        <v>Time = time()</v>
-        <v>Seconds = int()</v>
-      </type>
       <desc>
         <p>This function computes the number of gregorian seconds
           starting with year 0 and ending at the given date and time.</p>
       </desc>
     </func>
     <func>
-      <name>day_of_the_week(Date) -> DayNumber</name>
-      <name>day_of_the_week(Year, Month, Day) -> DayNumber</name>
+      <name name="day_of_the_week" arity="1"/>
+      <name name="day_of_the_week" arity="3"/>
       <fsummary>Compute the day of the week</fsummary>
-      <type>
-        <v>Date = date()</v>
-        <v>DayNumber = 1..7</v>
-      </type>
+      <type variable="Date" name_i="1"/>
+      <type variable="Year"/>
+      <type variable="Month"/>
+      <type variable="Day"/>
       <desc>
-        <p>This function computes the day of the week given <c>Year</c>,
-          <c>Month</c> and <c>Day</c>. The return value denotes the day
+        <p>This function computes the day of the week given <c><anno>Year</anno></c>,
+          <c><anno>Month</anno></c> and <c><anno>Day</anno></c>. The return value denotes the day
           of the week as <c>1</c>: Monday, <c>2</c>: Tuesday, and so on.</p>
       </desc>
     </func>
     <func>
-      <name>gregorian_days_to_date(Days) -> Date</name>
+      <name name="gregorian_days_to_date" arity="1"/>
       <fsummary>Compute the date given the number of gregorian days</fsummary>
-      <type>
-        <v>Days = int()</v>
-        <v>Date = date()</v>
-      </type>
       <desc>
         <p>This function computes the date given the number of
           gregorian days.</p>
       </desc>
     </func>
     <func>
-      <name>gregorian_seconds_to_datetime(Seconds) -> {Date, Time}</name>
+      <name name="gregorian_seconds_to_datetime" arity="1"/>
       <fsummary>Compute the date given the number of gregorian days</fsummary>
-      <type>
-        <v>Seconds = int()</v>
-        <v>Date = date()</v>
-        <v>Time = time()</v>
-      </type>
       <desc>
         <p>This function computes the date and time from the given
           number of gregorian seconds.</p>
       </desc>
     </func>
     <func>
-      <name>is_leap_year(Year) -> bool()</name>
+      <name name="is_leap_year" arity="1"/>
       <fsummary>Check if a year is a leap year</fsummary>
       <desc>
         <p>This function checks if a year is a leap year.</p>
       </desc>
     </func>
     <func>
-      <name>iso_week_number() -> IsoWeekNumber</name>
+      <name name="iso_week_number" arity="0"/>
       <fsummary>Compute the iso week number for the actual date</fsummary>
-      <type>
-        <v>IsoWeekNumber = {int(), int()}</v>
-      </type>
       <desc>
         <p>This function returns the tuple {Year, WeekNum} representing
           the iso week number for the actual date. For determining the
@@ -174,42 +199,34 @@ time() = {Hour, Minute, Second}
       </desc>
     </func>
     <func>
-      <name>iso_week_number(Date) -> IsoWeekNumber</name>
+      <name name="iso_week_number" arity="1"/>
       <fsummary>Compute the iso week number for the given date</fsummary>
-      <type>
-        <v>Date = date()</v>
-        <v>IsoWeekNumber = {int(), int()}</v>
-      </type>
       <desc>
         <p>This function returns the tuple {Year, WeekNum} representing
           the iso week number for the given date.</p>
       </desc>
     </func>
     <func>
-      <name>last_day_of_the_month(Year, Month) -> int()</name>
+      <name name="last_day_of_the_month" arity="2"/>
       <fsummary>Compute the number of days in a month</fsummary>
       <desc>
         <p>This function computes the number of days in a month.</p>
       </desc>
     </func>
     <func>
-      <name>local_time() -> {Date, Time}</name>
+      <name name="local_time" arity="0"/>
       <fsummary>Compute local time</fsummary>
-      <type>
-        <v>Date = date()</v>
-        <v>Time = time()</v>
-      </type>
       <desc>
         <p>This function returns the local time reported by
           the underlying operating system.</p>
       </desc>
     </func>
     <func>
-      <name>local_time_to_universal_time({Date1, Time1}) -> {Date2, Time2}</name>
+      <name name="local_time_to_universal_time" arity="1"/>
       <fsummary>Convert from local time to universal time (deprecated)</fsummary>
       <desc>
         <p>This function converts from local time to Universal 
-          Coordinated Time (UTC). <c>Date1</c> must refer to a local
+          Coordinated Time (UTC). <c><anno>DateTime1</anno></c> must refer to a local
           date after Jan 1, 1970.</p>
         <warning>
           <p>This function is deprecated. Use
@@ -222,15 +239,11 @@ time() = {Hour, Minute, Second}
       </desc>
     </func>
     <func>
-      <name>local_time_to_universal_time_dst({Date1, Time1}) -> [{Date, Time}]</name>
+      <name name="local_time_to_universal_time_dst" arity="1"/>
       <fsummary>Convert from local time to universal time(s)</fsummary>
-      <type>
-        <v>Date1 = Date = date()</v>
-        <v>Time1 = Time = time()</v>
-      </type>
       <desc>
         <p>This function converts from local time to Universal
-          Coordinated Time (UTC). <c>Date1</c> must refer to a local
+          Coordinated Time (UTC). <c><anno>DateTime1</anno></c> must refer to a local
           date after Jan 1, 1970.</p>
         <p>The return value is a list of 0, 1 or 2 possible UTC times:</p>
         <taglist>
@@ -258,65 +271,48 @@ time() = {Hour, Minute, Second}
       </desc>
     </func>
     <func>
-      <name>now_to_local_time(Now) -> {Date, Time}</name>
+      <name name="now_to_local_time" arity="1"/>
       <fsummary>Convert now to local date and time</fsummary>
-      <type>
-        <v>Now -- see erlang:now/0</v>
-        <v>Date = date()</v>
-        <v>Time = time()</v>
-      </type>
       <desc>
         <p>This function returns local date and time converted from
           the return value from <c>erlang:now()</c>.</p>
       </desc>
     </func>
     <func>
-      <name>now_to_universal_time(Now) -> {Date, Time}</name>
-      <name>now_to_datetime(Now) -> {Date, Time}</name>
+      <name name="now_to_universal_time" arity="1"/>
+      <name name="now_to_datetime" arity="1"/>
       <fsummary>Convert now to date and time</fsummary>
-      <type>
-        <v>Now -- see erlang:now/0</v>
-        <v>Date = date()</v>
-        <v>Time = time()</v>
-      </type>
       <desc>
         <p>This function returns Universal Coordinated Time (UTC)
           converted from the return value from <c>erlang:now()</c>.</p>
       </desc>
     </func>
     <func>
-      <name>seconds_to_daystime(Seconds) -> {Days, Time}</name>
+      <name name="seconds_to_daystime" arity="1"/>
       <fsummary>Compute days and time from seconds</fsummary>
-      <type>
-        <v>Seconds = Days = int()</v>
-        <v>Time = time()</v>
-      </type>
       <desc>
         <p>This function transforms a given number of seconds into days,
-          hours, minutes, and seconds. The <c>Time</c> part is always
-          non-negative, but <c>Days</c> is negative if the argument
-          <c>Seconds</c> is.</p>
+          hours, minutes, and seconds. The <c><anno>Time</anno></c> part is always
+          non-negative, but <c><anno>Days</anno></c> is negative if the argument
+          <c><anno>Seconds</anno></c> is.</p>
       </desc>
     </func>
     <func>
-      <name>seconds_to_time(Seconds) -> Time</name>
+      <name name="seconds_to_time" arity="1"/>
       <fsummary>Compute time from seconds</fsummary>
-      <type>
-        <v>Seconds = int() &lt; 86400</v>
-        <v>Time = time()</v>
-      </type>
+      <type name="secs_per_day"/>
       <desc>
         <p>This function computes the time from the given number of
-          seconds. <c>Seconds</c> must be less than the number of
+          seconds. <c><anno>Seconds</anno></c> must be less than the number of
           seconds per day (86400).</p>
       </desc>
     </func>
     <func>
-      <name>time_difference(T1, T2) -> {Days, Time}</name>
+      <name name="time_difference" arity="2"/>
       <fsummary>Compute the difference between two times (deprecated)</fsummary>
       <desc>
-        <p>This function returns the difference between two <c>{Date, Time}</c> tuples. <c>T2</c> should refer to an epoch later
-          than <c>T1</c>.</p>
+        <p>This function returns the difference between two <c>{Date, Time}</c> tuples. <c><anno>T2</anno></c> should refer to an epoch later
+          than <c><anno>T1</anno></c>.</p>
         <warning>
           <p>This function is obsolete. Use the conversion functions for
             gregorian days and seconds instead.</p>
@@ -324,24 +320,17 @@ time() = {Hour, Minute, Second}
       </desc>
     </func>
     <func>
-      <name>time_to_seconds(Time) -> Seconds</name>
+      <name name="time_to_seconds" arity="1"/>
       <fsummary>Compute the number of seconds since midnight up to  the given time</fsummary>
-      <type>
-        <v>Time = time()</v>
-        <v>Seconds = int()</v>
-      </type>
+      <type name="secs_per_day"/>
       <desc>
         <p>This function computes the number of seconds since midnight
           up to the specified time.</p>
       </desc>
     </func>
     <func>
-      <name>universal_time() -> {Date, Time}</name>
+      <name name="universal_time" arity="0"/>
       <fsummary>Compute universal time</fsummary>
-      <type>
-        <v>Date = date()</v>
-        <v>Time = time()</v>
-      </type>
       <desc>
         <p>This function returns the Universal Coordinated Time (UTC)
           reported by the underlying operating system. Local time is
@@ -349,25 +338,22 @@ time() = {Hour, Minute, Second}
       </desc>
     </func>
     <func>
-      <name>universal_time_to_local_time({Date1, Time1}) -> {Date2, Time2}</name>
+      <name name="universal_time_to_local_time" arity="1"/>
       <fsummary>Convert from universal time to local time</fsummary>
-      <type>
-        <v>Date1 = Date2 = date()</v>
-        <v>Time1 = Time2 = time()</v>
-      </type>
       <desc>
         <p>This function converts from Universal Coordinated Time (UTC)
-          to local time. <c>Date1</c> must refer to a date after Jan 1, 
+          to local time. <c><anno>DateTime</anno></c> must refer to a date after Jan 1,
           1970.</p>
       </desc>
     </func>
     <func>
-      <name>valid_date(Date) -> bool()</name>
-      <name>valid_date(Year, Month, Day) -> bool()</name>
+      <name name="valid_date" arity="1"/>
+      <name name="valid_date" arity="3"/>
+      <type variable="Date" name_i="1"/>
+      <type variable="Year"/>
+      <type variable="Month"/>
+      <type variable="Day"/>
       <fsummary>Check if a date is valid</fsummary>
-      <type>
-        <v>Date = date()</v>
-      </type>
       <desc>
         <p>This function checks if a date is a valid.</p>
       </desc>