From 664ce87016fc38275e05614ee0907b8dd40f2094 Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Thu, 21 Nov 2002 07:16:01 +0000 Subject: style.css: Update. 2002-11-21 Phil Edwards * docs/doxygen/style.css: Update. * docs/doxygen/user.cfg.in: Update. * docs/html/documentation.html: Regenerate. * docs/html/17_intro/howto.html: Tweak I/O sentry entry. * docs/html/27_io/howto.html: New section on headers. * docs/html/faq/index.html: Add i386 threading entry. * docs/html/faq/index.txt: Regenerate. * docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html: Import R23. From-SVN: r59326 --- libstdc++-v3/docs/doxygen/style.css | 45 +- libstdc++-v3/docs/doxygen/user.cfg.in | 157 +++++- libstdc++-v3/docs/html/17_intro/howto.html | 5 +- libstdc++-v3/docs/html/27_io/howto.html | 133 +++++ libstdc++-v3/docs/html/documentation.html | 3 +- libstdc++-v3/docs/html/ext/lwg-active.html | 784 ++++++++++++++++++++++++-- libstdc++-v3/docs/html/ext/lwg-defects.html | 264 ++++----- libstdc++-v3/docs/html/faq/index.html | 15 +- libstdc++-v3/docs/html/faq/index.txt | 832 ++++++++++++++-------------- 9 files changed, 1628 insertions(+), 610 deletions(-) (limited to 'libstdc++-v3/docs') diff --git a/libstdc++-v3/docs/doxygen/style.css b/libstdc++-v3/docs/doxygen/style.css index 5e43005..e527a57 100644 --- a/libstdc++-v3/docs/doxygen/style.css +++ b/libstdc++-v3/docs/doxygen/style.css @@ -1,4 +1,5 @@ H1 { text-align: center; } +CAPTION { font-weight: bold } A.qindex {} A.qindexRef {} A.el { text-decoration: none; font-weight: bold } @@ -10,15 +11,39 @@ DL.el { margin-left: -1cm } DIV.fragment { width: 100%; border: none; background-color: #eeeeee } DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px } TD.md { background-color: #f2f2ff; font-weight: bold; } -TD.mdname1 { background-color: #f2f2ff; font-weight: bold; font-style: italic; } -TD.mdname { background-color: #f2f2ff; font-weight: bold; font-style: italic; width: 600px; } +TD.mdname1 { background-color: #f2f2ff; font-weight: bold; color: #602020; } +TD.mdname { background-color: #f2f2ff; font-weight: bold; color: #602020; width: 600px; } DIV.groupHeader { margin-left: 16px; margin-top: 12px; margin-bottom: 6px; font-weight: bold } DIV.groupText { margin-left: 16px; font-style: italic; font-size: smaller } -FONT.keyword { color: #008000 } -FONT.keywordtype { color: #604020 } -FONT.keywordflow { color: #e08000 } -FONT.comment { color: #800000 } -FONT.preprocessor { color: #806020 } -FONT.stringliteral { color: #002080 } -FONT.charliteral { color: #008080 } -.smallertext { font-size: smaller } +BODY { background: white } +TD.indexkey { + background-color: #eeeeff; + font-weight: bold; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px +} +TD.indexvalue { + background-color: #eeeeff; + font-style: italic; + padding-right : 10px; + padding-top : 2px; + padding-left : 10px; + padding-bottom : 2px; + margin-left : 0px; + margin-right : 0px; + margin-top : 2px; + margin-bottom : 2px +} +span.keyword { color: #008000 } +span.keywordtype { color: #604020 } +span.keywordflow { color: #e08000 } +span.comment { color: #800000 } +span.preprocessor { color: #806020 } +span.stringliteral { color: #002080 } +span.charliteral { color: #008080 } diff --git a/libstdc++-v3/docs/doxygen/user.cfg.in b/libstdc++-v3/docs/doxygen/user.cfg.in index dff2f3f..966d6e8 100644 --- a/libstdc++-v3/docs/doxygen/user.cfg.in +++ b/libstdc++-v3/docs/doxygen/user.cfg.in @@ -1,4 +1,4 @@ -# Doxyfile 1.2.12 +# Doxyfile 1.2.18 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project @@ -43,9 +43,11 @@ OUTPUT_DIRECTORY = @outdir@ # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. # The default language is English, other supported languages are: -# Brazilian, Chinese, Croatian, Czech, Danish, Dutch, Finnish, French, -# German, Hungarian, Italian, Japanese, Korean, Norwegian, Polish, -# Portuguese, Romanian, Russian, Slovak, Slovene, Spanish and Swedish. +# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, +# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en +# (Japanese with english messages), Korean, Norwegian, Polish, Portuguese, +# Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish and Ukrainian. + OUTPUT_LANGUAGE = English @@ -66,6 +68,12 @@ EXTRACT_PRIVATE = YES EXTRACT_STATIC = YES +# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) +# defined locally in source files will be included in the documentation. +# If set to NO only classes defined in header files are included. + +EXTRACT_LOCAL_CLASSES = NO + # If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all # undocumented members of documented classes, files or namespaces. # If set to NO (the default) these members will be included in the @@ -81,6 +89,13 @@ HIDE_UNDOC_MEMBERS = YES HIDE_UNDOC_CLASSES = YES +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all +# friend (class|struct|union) declarations. +# If set to NO (the default) these declarations will be included in the +# documentation. + +HIDE_FRIEND_COMPOUNDS = NO + # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will # include brief member descriptions after the members that are listed in # the file and class documentation (similar to JavaDoc). @@ -101,6 +116,14 @@ REPEAT_BRIEF = YES ALWAYS_DETAILED_SEC = YES +# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited +# members of a class in the documentation of that class as if those members were +# ordinary class members. Constructors, destructors and assignment operators of +# the base classes will not be shown. + +INLINE_INHERITED_MEMB = NO +# pedwards -- this is useful, but ch27 gets huge + # If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full # path before files name in the file list and in the header files. If set # to NO the shortest path that makes the file name unique will be used. @@ -167,6 +190,21 @@ SHOW_INCLUDE_FILES = YES JAVADOC_AUTOBRIEF = NO +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen +# treat a multi-line C++ special comment block (i.e. a block of //! or /// +# comments) as a brief description. This used to be the default behaviour. +# The new default is to treat a multi-line C++ comment block as a detailed +# description. Set this tag to YES if you prefer the old behaviour instead. + +MULTILINE_CPP_IS_BRIEF = YES + +# If the DETAILS_AT_TOP tag is set to YES then Doxygen +# will output the detailed description near the top, like JavaDoc. +# If set to NO, the detailed description appears after the member +# documentation. + +DETAILS_AT_TOP = NO + # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented # member inherits the documentation from any documented member that it # reimplements. @@ -183,7 +221,7 @@ INLINE_INFO = YES # alphabetically by member name. If set to NO the members will appear in # declaration order. -SORT_MEMBER_DOCS = NO +SORT_MEMBER_DOCS = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC # tag is set to YES, then doxygen will reuse the documentation of the first @@ -215,6 +253,12 @@ GENERATE_TESTLIST = NO GENERATE_BUGLIST = YES +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or +# disable (NO) the deprecated list. This list is created by putting +# \deprecated commands in the documentation. + +GENERATE_DEPRECATEDLIST= YES + # This tag can be used to specify a number of aliases that acts # as commands in the documentation. An alias has the form "name=value". # For example adding "sideeffect=\par Side Effects:\n" will allow you to @@ -222,7 +266,8 @@ GENERATE_BUGLIST = YES # will result in a user defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = "doctodo=@todo\nDoc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more." +ALIASES = "doctodo=@todo\nDoc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more." \ +"isiosfwd=One of the @link s27_2_iosfwd I/O forward declarations @endlink" # The ENABLED_SECTIONS tag can be used to enable conditional # documentation sections, marked by \if sectionname ... \endif. @@ -237,7 +282,7 @@ ENABLED_SECTIONS = @enabled_sections@ # documentation can be controlled using \showinitializer or \hideinitializer # command in the documentation regardless of this setting. -MAX_INITIALIZER_LINES = 30 +MAX_INITIALIZER_LINES = 0 # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. @@ -246,6 +291,13 @@ MAX_INITIALIZER_LINES = 30 OPTIMIZE_OUTPUT_FOR_C = NO +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources +# only. Doxygen will then generate output that is more tailored for Java. +# For instance namespaces will be presented as packages, qualified scopes +# will look different, etc. + +OPTIMIZE_OUTPUT_JAVA = NO + # Set the SHOW_USED_FILES tag to NO to disable the list of files generated # at the bottom of the documentation of classes and structs. If set to YES the # list will mention the files that were used to generate the documentation. @@ -325,12 +377,18 @@ RECURSIVE = YES EXCLUDE = Makefile CVS +# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories +# that are symbolic links (a Unix filesystem feature) are excluded from the input. + +EXCLUDE_SYMLINKS = NO + # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude # certain files from those directories. EXCLUDE_PATTERNS = CVS \ - stamp-* + stamp-* \ + Makefile # The EXAMPLE_PATH tag can be used to specify one or more files or # directories that contain example code fragments that are included (see @@ -369,7 +427,7 @@ INPUT_FILTER = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will be used to filter the input files when producing source -# files to browse. +# files to browse (i.e. when SOURCE_BROWSER is set to YES). FILTER_SOURCE_FILES = NO @@ -437,6 +495,12 @@ GENERATE_HTML = @do_html@ HTML_OUTPUT = @html_output_dir@ +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for +# each generated HTML page (for example: .htm,.php,.asp). If it is left blank +# doxygen will generate files with .html extension. + +HTML_FILE_EXTENSION = .html + # The HTML_HEADER tag can be used to specify a personal HTML header for # each generated HTML page. If it is left blank doxygen will generate a # standard header. @@ -469,6 +533,20 @@ HTML_ALIGN_MEMBERS = YES GENERATE_HTMLHELP = NO +# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can +# be used to specify the file name of the resulting .chm file. You +# can add a path in front of the file if the result should not be +# written to the html output dir. + +CHM_FILE = + +# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can +# be used to specify the location (absolute path including file name) of +# the HTML help compiler (hhc.exe). If non empty doxygen will try to run +# the html help compiler on the generated index.hhp. + +HHC_LOCATION = + # If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag # controls if a separate .chi index file is generated (YES) or that # it should be included in the master .chm file (NO). @@ -528,6 +606,17 @@ GENERATE_LATEX = NO LATEX_OUTPUT = latex +# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to +# be invoked. If left blank `latex' will be used as the default command name. + +LATEX_CMD_NAME = latex + +# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to +# generate index for LaTeX. If left blank `makeindex' will be used as the +# default command name. + +MAKEINDEX_CMD_NAME = makeindex + # If the COMPACT_LATEX tag is set to YES Doxygen generates more compact # LaTeX documents. This may be useful for small projects and may help to # save some trees in general. @@ -654,6 +743,30 @@ MAN_LINKS = NO GENERATE_XML = NO +# The XML_SCHEMA tag can be used to specify an XML schema, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_SCHEMA = + +# The XML_DTD tag can be used to specify an XML DTD, +# which can be used by a validating XML parser to check the +# syntax of the XML files. + +XML_DTD = + +#--------------------------------------------------------------------------- +# configuration options for the AutoGen Definitions output +#--------------------------------------------------------------------------- + +# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will +# generate an AutoGen Definitions (see autogen.sf.net) file +# that captures the structure of the code including all +# documentation. Note that this feature is still experimental +# and incomplete at the moment. + +GENERATE_AUTOGEN_DEF = NO + #--------------------------------------------------------------------------- # Configuration options related to the preprocessor #--------------------------------------------------------------------------- @@ -707,6 +820,8 @@ INCLUDE_FILE_PATTERNS = ### completely broken, and the presence of the macros confuses the parser. PREDEFINED = _GLIBCPP_DEPRECATED \ + _GLIBCPP_USE_WCHAR_T \ + _GLIBCPP_USE_LONG_LONG \ __glibcpp_class_requires="//" \ __glibcpp_class_requires2="//" \ __glibcpp_class_requires3="//" \ @@ -745,6 +860,12 @@ GENERATE_TAGFILE = ALLEXTERNALS = YES +# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will +# be listed. + +EXTERNAL_GROUPS = YES + # The PERL_PATH should be the absolute path and name of the perl script # interpreter (i.e. the result of `which perl'). @@ -762,6 +883,12 @@ PERL_PATH = /usr/bin/perl CLASS_DIAGRAMS = YES +# If set to YES, the inheritance and collaboration graphs will hide +# inheritance and usage relations if the target is undocumented +# or is not a class. + +HIDE_UNDOC_RELATIONS = YES + # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz, a graph visualization # toolkit from AT&T and Lucent Bell Labs. The other options in this section @@ -788,12 +915,6 @@ COLLABORATION_GRAPH = YES TEMPLATE_RELATIONS = YES -# If set to YES, the inheritance and collaboration graphs will hide -# inheritance and usage relations if the target is undocumented -# or is not a class. - -HIDE_UNDOC_RELATIONS = YES - # If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT # tags are set to YES then doxygen will generate a graph for each documented # file showing the direct and indirect include dependencies of the file with @@ -813,6 +934,12 @@ INCLUDED_BY_GRAPH = YES GRAPHICAL_HIERARCHY = YES +# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images +# generated by dot. Possible values are png, jpg, or gif +# If left blank png will be used. + +DOT_IMAGE_FORMAT = png + # The tag DOT_PATH can be used to specify the path where the dot tool can be # found. If left blank, it is assumed the dot tool can be found on the path. diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index 5888a54..9d10bec 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -261,8 +261,9 @@ on the --enable-libio choice: for stdio, if the written data is already in the stdio buffer, the data may be completely safe!

-

I/O sentry ctor/dtor They can perform additional work - than the minimum required. I don't think we're currently taking +

[27.6.1.1.2],
+ [27.6.2.3] The I/O sentry ctor and dtor can perform + additional work than the minimum required. We are not currently taking advantage of this yet.

[27.7.1.3]/16,
diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index b4a5925..d7a984e 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -34,6 +34,7 @@

  • More on binary I/O
  • Pathetic performance? Ditch C.
  • Threads and I/O
    • +
  • Which header?
    • @@ -558,6 +559,138 @@ "interesting" problems.

    +
    +

    Which header?

    +

    To minimize the time you have to wait on the compiler, it's good to + only include the headers you really need. Many people simply include + <iostream> when they don't need to -- and that can penalize + your runtime as well. Here are some tips on which header to use + for which situations, starting with the simplest. +

    +

    <iosfwd> should be included whenever you simply + need the name of an I/O-related class, such as + "ofstream" or "basic_streambuf". Like the name + implies, these are forward declarations. (A word to all you fellow + old school programmers: trying to forward declare classes like + "class istream;" won't work. Look in the iosfwd header if + you'd like to know why.) For example, +

    + 
    +    #include <iosfwd>
+
+    class MyClass
+    {
+        ....
+        std::ifstream   input_file;
+    };
+
+    extern std::ostream& operator<< (std::ostream&, MyClass&);
+
    +

    <ios> declares the base classes for the entire + I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the + counting types std::streamoff and std::streamsize, the file + positioning type std::fpos, and the various manipulators like + std::hex, std::fixed, std::noshowbase, and so forth. +

    +

    The ios_base class is what holds the format flags, the state flags, + and the functions which change them (setf(), width(), precision(), + etc). You can also store extra data and register callback functions + through ios_base, but that has been historically underused. Anything + which doesn't depend on the type of characters stored is consolidated + here. +

    +

    The template class basic_ios is the highest template class in the + hierarchy; it is the first one depending on the character type, and + holds all general state associated with that type: the pointer to the + polymorphic stream buffer, the facet information, etc. +

    +

    <streambuf> declares the template class + basic_streambuf, and two standard instantiations, streambuf and + wstreambuf. If you need to work with the vastly useful and capable + stream buffer classes, e.g., to create a new form of storage + transport, this header is the one to include. +

    +

    <istream>/<ostream> are + the headers to include when you are using the >>/<< + interface, or any of the other abstract stream formatting functions. + For example, +

    + 
    +    #include <istream>
+
+    std::ostream& operator<< (std::ostream& os, MyClass& c)
+    {
+       return os << c.data1() << c.data2();
+    }
+
    +

    The std::istream and std::ostream classes are the abstract parents of + the various concrete implementations. If you are only using the + interfaces, then you only need to use the appropriate interface header. +

    +

    <iomanip> provides "extractors and inserters + that alter information maintained by class ios_base and its dervied + classes," such as std::setprecision and std::setw. If you need + to write expressions like os << setw(3); or + is >> setbase(8);, you must include <iomanip>. +

    +

    <sstream>/<fstream> + declare the six stringstream and fstream classes. As they are the + standard concrete descendants of istream and ostream, you will already + know about them. +

    +

    Finally, <iostream> provides the eight standard + global objects (cin, cout, etc). To do this correctly, this header + also provides the contents of the <istream> and <ostream> + headers, but nothing else. The contents of this header look like +

    + 
    +    #include <ostream>
+    #include <istream>
+
+    namespace std
+    {
+        extern istream cin;
+        extern ostream cout;
+        ....
+
+        // this is explained below
+        static ios_base::Init __foo;    // not its real name
+    }
+
    +

    Now, the runtime penalty mentioned previously: the global objects + must be initialized before any of your own code uses them; this is + guaranteed by the standard. Like any other global object, they must + be initialized once and only once. This is typically done with a + construct like the one above, and the nested class ios_base::Init is + specified in the standard for just this reason. +

    +

    How does it work? Because the header is included before any of your + code, the __foo object is constructed before any of + your objects. (Global objects are built in the order in which they + are declared, and destroyed in reverse order.) The first time the + constructor runs, the eight stream objects are set up. +

    +

    The static keyword means that each object file compiled + from a source file containing <iostream> will have its own + private copy of __foo. There is no specified order + of construction across object files (it's one of those pesky NP + problems that make life so interesting), so one copy in each object + file means that the stream objects are guaranteed to be set up before + any of your code which uses them could run, thereby meeting the + requirements of the standard. +

    +

    The penalty, of course, is that after the first copy of + __foo is constructed, all the others are just wasted + processor time. The time spent is merely for an increment-and-test + inside a function call, but over several dozen or hundreds of object + files, that time can add up. (It's not in a tight loop, either.) +

    +

    The lesson? Only include <iostream> when you need to use one of + the standard objects in that source file; you'll pay less startup + time. Only include the header files you need to in general; your + compile times will go down when there's less parsing work to do. +

    + diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index a4a79e3..8c40fb0 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -66,7 +66,7 @@ diff --git a/libstdc++-v3/docs/html/ext/lwg-active.html b/libstdc++-v3/docs/html/ext/lwg-active.html index c8d33f3..a69d6c6 100644 --- a/libstdc++-v3/docs/html/ext/lwg-active.html +++ b/libstdc++-v3/docs/html/ext/lwg-active.html @@ -5,11 +5,11 @@ - + - + @@ -17,10 +17,10 @@ - +
    Doc. no.J16/02-0027 = WG21 N1369J16/02-0048 = WG21 N1390
    Date:10 May 200210 Sep 2002
    Project:
    Reply to:Matt Austern <austern@research.att.com>Matt Austern <austern@apple.com>
    -

    C++ Standard Library Active Issues List (Revision 22)

    +

    C++ Standard Library Active Issues List (Revision 23)

    Reference ISO/IEC IS 14882:1998(E)

    Also see: