[PATCH] Improve implementation-defined docs for libstdc++

[PATCH] Improve implementation-defined docs for libstdc++

[Jonathan Wakely]

[-- Attachment #1: Type: text/plain, Size: 530 bytes --]

We're required to document anything the standard says is
implementation-defined. This adds a few missing things to the C++98
and C++11 docs, and adds the new stuff for C++17.

I'll regenerate the HTML soon, as I'll be making some more doc changes
next week.

	* doc/xml/manual/status_cxx1998.xml: Improve documentation of
	implementation-defined properties.
	* doc/xml/manual/status_cxx2011.xml: Likewise.
	* doc/xml/manual/status_cxx2017.xml: Likewise.

Committed to trunk. I'll backport the relevant parts to the branches
too.


[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 11280 bytes --]

commit f31956238e6e47f44a333e48fc903c6b6b6f8835
Author: Jonathan Wakely <jwakely@redhat.com>
Date:   Fri Oct 7 16:17:28 2016 +0100

    Improve implementation-defined docs for libstdc++
    
    	* doc/xml/manual/status_cxx1998.xml: Improve documentation of
    	implementation-defined properties.
    	* doc/xml/manual/status_cxx2011.xml: Likewise.
    	* doc/xml/manual/status_cxx2017.xml: Likewise.

diff --git a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
index 1679ee0..6afb016 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx1998.xml
@@ -1087,19 +1087,14 @@ particular release.
       <emphasis>[18.6.1]/8</emphasis> (exception),
       <emphasis>[18.6.2.1]/5</emphasis> (bad_exception):  The <code>what()</code>
       member function of class <code>std::exception</code>, and these other
-      classes publicly derived from it, simply returns the name of the
-      class.  But they are the <emphasis>mangled</emphasis> names; you will need to call
-      <code>c++filt</code> and pass the names as command-line parameters to
-      demangle them, or call a
-      <link linkend="manual.ext.demangle">runtime demangler function</link>.
-      (The classes in <code>&lt;stdexcept&gt;</code> have constructors which
-      require an argument to use later for <code>what()</code> calls, so the
-      problem of <code>what()</code>'s value does not arise in most
-      user-defined exceptions.)
+      classes publicly derived from it, returns the name of the
+      class, e.g. <literal>"std::bad_alloc"</literal>.
    </para>
    <para><emphasis>[18.5.1]/7</emphasis> The return value of
-      <code>std::type_info::name()</code> is the mangled type name (see the
-      previous entry for more).
+      <code>std::type_info::name()</code> is the mangled type name.
+      You will need to call <code>c++filt</code> and pass the names as
+      command-line parameters to demangle them, or call a
+      <link linkend="manual.ext.demangle">runtime demangler function</link>.
    </para>
    <para><emphasis>[20.1.5]/5</emphasis> <emphasis>"Implementors are encouraged to
       supply libraries that can accept allocators that encapsulate more
@@ -1114,6 +1109,7 @@ particular release.
    </para>
    <para><emphasis>[21.1.3.1]/3,4</emphasis>,
       <emphasis>[21.1.3.2]/2</emphasis>,
+      <emphasis>[21.3]/6 basic_string::iterator, basic_string::const_iterator</emphasis>,
       <emphasis>[23.*]'s foo::iterator</emphasis>,
       <emphasis>[27.*]'s foo::*_type</emphasis>,
       <emphasis>others...</emphasis>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
index e1b372d..83a266f 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
@@ -2572,9 +2572,41 @@ particular release.
    </para>
 
    <para>
+      <emphasis>17.6.5.12 [res.on.exception.handling]</emphasis>
+      There are no implementation-defined exception classes, only standard
+      exception classes (or classes derived from them) will be thrown.
+   </para>
+
+   <para>
+      <emphasis>17.6.5.14 [value.error.codes]</emphasis>
+      The <classname>error_category</classname> for errors originating outside
+      the OS, and the possible error code values for each error category,
+      should be documented here.
+   </para>
+
+   <para>
+      <emphasis>18.6.2.2 [new.badlength]</emphasis>
+      <function>what()</function> returns
+      <literal>"std::bad_array_new_length"</literal>.
+   </para>
+
+   <para>
+      <emphasis>20.6.9.1 [allocator.member]/5</emphasis>
+      Over-aligned types are not supported by
+      <classname>std::allocator</classname>.
+   </para>
+
+   <para>
       <emphasis>20.7.2.2.1 [util.smartptr.shared.const]</emphasis>
-      Only <classname>bad_alloc</classname> (or types derived from it) will
-      be thrown.
+      When a <classname>shared_ptr</classname> constructor fails
+      <classname>bad_alloc</classname> (or types derived from it) will
+      be thrown, or when an allocator is passed to the constructor then any
+      exceptions thrown by the allocator.
+   </para>
+
+   <para>
+      <emphasis>20.7.2.0 [util.smartptr.weakptr]</emphasis>
+      <code>what()</code> returns <literal>"bad_weak_ptr"</literal>.
    </para>
 
    <para>
@@ -2584,6 +2616,18 @@ particular release.
    </para>
 
    <para>
+      <emphasis>20.11.7.1 [time.clock.system]/3, /4</emphasis>
+      Time point values are truncated to <code>time_t</code> values.
+      There is no loss of precision for conversions in the other direction.
+   </para>
+
+   <para>
+      <emphasis>20.15.7 [meta.trans]/2</emphasis>
+      <classname>aligned_storage</classname> does not support extended
+      alignment.
+   </para>
+
+   <para>
       <emphasis>21.2.3.2 [char.traits.specializations.char16_t]</emphasis>,
       <emphasis>21.2.3.3 [char.traits.specializations.char32_t]</emphasis>
       The types <classname>u16streampos</classname> and
@@ -2593,6 +2637,11 @@ particular release.
    </para>
 
    <para>
+      <emphasis>22.3.1 [locale]</emphasis>
+      There is one global locale for the whole program, not per-thread.
+   </para>
+
+   <para>
       <emphasis>22.4.5.1.2 [locale.time.get.virtuals]</emphasis>,
       <emphasis>22.4.5.3.2 [locale.time.put.virtuals]</emphasis>
       Additional supported formats should be documented here.
@@ -2604,6 +2653,13 @@ particular release.
    </para>
 
    <para>
+      <emphasis>23.3.2.1 [array.overview]</emphasis>
+      <classname>array&lt;T, N&gt;::iterator</classname> is <code>T*</code> and
+      <classname>array&lt;T, N&gt;::const_iterator</classname> is
+      <code>const T*</code>.
+   </para>
+
+   <para>
       <emphasis>23.5.4.2 [unord.map.cnstr]</emphasis>,
       <emphasis>23.5.5.2 [unord.multimap.cnstr]</emphasis>,
       <emphasis>23.5.6.2 [unord.set.cnstr]</emphasis>,
@@ -2652,6 +2708,20 @@ particular release.
    </para>
 
    <para>
+      <emphasis>27.8.2.1 [stringbuf.cons]</emphasis>
+      Whether the sequence pointers are copied by the
+      <classname>basic_stringbuf</classname> move constructor should be
+      documented here.
+   </para>
+
+   <para>
+      <emphasis>27.9.1.2 [filebuf.cons]</emphasis>
+      Whether the sequence pointers are copied by the
+      <classname>basic_filebuf</classname> move constructor should be
+      documented here.
+   </para>
+
+   <para>
       <emphasis>28.5.1 [re.synopt]</emphasis>,
       <emphasis> 28.5.2 [re.matchflag] </emphasis>,
       <emphasis> 28.5.3 [re.err] </emphasis>
@@ -2666,6 +2736,12 @@ particular release.
    </para>
 
    <para>
+      <emphasis>29.4 [atomics.lockfree]</emphasis>
+      The values of the <code>ATOMIC_xxx_LOCK_FREE</code> macros depend on
+      the target and cannot be listed here.
+   </para>
+
+   <para>
       <emphasis>30.2.3 [thread.req.native]/1</emphasis>
       <classname>native_handle_type</classname> and
       <methodname>native_handle</methodname> are provided. The handle types
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
index f1d709e..c03978e 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2017.xml
@@ -876,4 +876,112 @@ Feature-testing recommendations for C++</link>.
 </tgroup>
 </table>
 
+<section xml:id="iso.2017.specific" xreflabel="Implementation Specific"><info><title>Implementation Specific Behavior</title></info>
+
+   <para>For behaviour which is also specified by previous standards,
+      see <link linkend="iso.1998.specific">C++ 1998/2003 Implementation
+      Specific Behavior</link> and <link linkend="iso.2011.specific">C++
+      2011 Implementation Specific Behavior</link>. This section only
+      documents behaviour which is new in the 2017 standard.
+   </para>
+
+   <para>
+      <emphasis>20.6.5 [optional.bad_optional_access]</emphasis>
+      <code>what()</code> returns <literal>"bad optional access"</literal>.
+   </para>
+
+   <para>
+      <emphasis>20.7.2 [variant.variant]</emphasis>
+      Whether <classname>variant</classname> supports over-aligned types
+      should be documented here.
+   </para>
+
+   <para>
+      <emphasis>20.7.10 [variant.bad.access]</emphasis>
+      <code>what()</code> returns <literal>"Unexpected index"</literal>.
+   </para>
+
+   <para>
+      <emphasis>20.12.5.2 [memory.resource.pool.options]</emphasis>
+      The limits for maximum number of blocks and largest allocation size
+      supported by <classname>pool_options</classname> should be documented
+      here.
+   </para>
+
+   <para>
+      <emphasis>20.12.6.1 [memory.resource.monotonic.buffer.ctor]</emphasis>
+      The default <code>next_buffer_size</code> and growth factor should
+      be documented here.
+   </para>
+
+   <para>
+      <emphasis>20.15.4.3 [meta.unary.prop]</emphasis>
+      The predicate condition for
+      <code>has_unique_object_representations</code> is true for all scalar
+      types except floating point types.
+   </para>
+
+   <para>
+      <emphasis>20.19.3 [execpol.type],
+      25.2.3 [algorithms.parallel.exec]</emphasis>
+      There are no implementation-defined execution policies.
+   </para>
+
+   <para>
+      <emphasis>22.4.2 [string.view.template]</emphasis>
+      <classname>basic_string_view&lt;C, T&gt;::iterator</classname> is
+      <code>C*</code> and
+      <classname>basic_string_view&lt;C, T&gt;::const_iterator</classname> is
+      <code>const C*</code>.
+   </para>
+
+
+   <para>
+      <emphasis>25.2.3 [algorithms.parallel.exec]</emphasis>
+      Threads of execution created by <classname>std::thread</classname>
+      provide concurrent forward progress guarantees, so threads of execution
+      implicitly created by the library will provide parallel forward
+      progress guarantees.
+   </para>
+
+   <para>
+      <emphasis>26.4.1 [cfenv.syn]</emphasis>
+      The effects of the <filename>&lt;cfenv&gt;</filename> functions
+      depends on whether the <code>FENV_ACCESS</code> pragma is supported,
+      and on the C library that provides the header.
+   </para>
+
+   <para>
+      <emphasis>26.6.9 [c.math.rand]</emphasis>
+      Whether the <function>rand</function> function may introduce data
+      races depends on the target C library that provides the function.
+   </para>
+
+   <para>
+      <emphasis>26.9.5 [sf.cmath]</emphasis>
+      The effect of calling the mathematical special functions with large
+      inputs should be documented here.
+   </para>
+
+   <para>
+      <emphasis>27.10.2.1 [fs.conform.9945]</emphasis>
+      The behavior of the filesystem library implementation will depend on
+      the target operating system. Some features will not be not supported
+      on some targets.
+   </para>
+
+   <para>
+      <emphasis>27.10.6 [fs.filesystem.syn]</emphasis>
+      The clock used for file times is
+      <classname>std::chrono::system_clock</classname>.
+   </para>
+
+   <para>
+      <emphasis>27.10.8 [path.generic]</emphasis>
+      dot-dot in the root-directory refers to the root-directory itself.
+   </para>
+
+
+</section>
+
 </section>