Rewritten documentation in QuickBook and Doxygen.

bug/bug.cpp

@@ -1,5 +1,10 @@
+//  Copyright Beman Dawes 2014
+//  Distributed under the Boost Software License, Version 1.0.
+//  www.boost.org/LICENSE_1_0.txt
+//
 //  filesystem/bug/bug.cpp
 
+//[bug_cpp
 #include <boost/detail/lightweight_test_report.hpp>
 #include <boost/filesystem.hpp>
 
@@ -13,7 +18,4 @@ int test_main(int, char*[]) // note name
 
     return ::boost::report_errors(); // required
 }
-
-//  Copyright Beman Dawes 2014
-//  Distributed under the Boost Software License, Version 1.0.
-//  www.boost.org/LICENSE_1_0.txt
+//]

doc/.gitignore

@@ -0,0 +1,2 @@
+html
+*_reference.xml

doc/Jamfile.v2

@@ -1,23 +1,151 @@
-# Boost Filesystem Library Example Jamfile
+# Copyright 2024 Andrey Semashev
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# https://www.boost.org/LICENSE_1_0.txt)
 
-# Copyright Beman Dawes 2010
+using quickbook ;
+using boostbook ;
+using doxygen ;
+using xsltproc ;
 
-# Distributed under the Boost Software License, Version 1.0.
-# See www.boost.org/LICENSE_1_0.txt
+import set ;
+import doxygen ;
+import xsltproc ;
+import notfile ;
+import path ;
+import project ;
+
+project boost/libs/filesystem/doc ;
+
+local doxygen_params =
+        <doxygen:param>RECURSIVE=YES
+        <doxygen:param>ALPHABETICAL_INDEX=YES
+        <doxygen:param>REPEAT_BRIEF=YES
+        <doxygen:param>ALWAYS_DETAILED_SEC=YES
+        <doxygen:param>BRIEF_MEMBER_DESC=NO
+        <doxygen:param>ABBREVIATE_BRIEF=YES
+        <doxygen:param>INHERIT_DOCS=YES
+        <doxygen:param>HIDE_UNDOC_MEMBERS=YES
+        <doxygen:param>HIDE_UNDOC_CLASSES=YES
+        <doxygen:param>HIDE_SCOPE_NAMES=YES
+        <doxygen:param>AUTOLINK_SUPPORT=YES
+        <doxygen:param>DISTRIBUTE_GROUP_DOC=NO
+        <doxygen:param>SUBGROUPING=NO
+        <doxygen:param>EXTRACT_ALL=NO
+        <doxygen:param>EXTRACT_PRIVATE=NO
+        <doxygen:param>BUILTIN_STL_SUPPORT=YES
+        <doxygen:param>ENABLE_PREPROCESSING=YES
+        <doxygen:param>MACRO_EXPANSION=YES
+        <doxygen:param>SHORT_NAMES=YES
+        <doxygen:param>TAB_SIZE=4
+        <doxygen:param>SOURCE_BROWSER=YES
+        <doxygen:param>VERBATIM_HEADERS=NO
+#        <doxygen:param>SEARCH_INCLUDES=YES
+#        <doxygen:param>"INCLUDE_PATH=../../.."
+#        <doxygen:param>EXCLUDE_SYMBOLS="detail detail::*"
+        <doxygen:param>"PREDEFINED=BOOST_FILESYSTEM_DOXYGEN \\
+                        BOOST_FILESYSTEM_DECL= \\
+                        BOOST_FILESYSTEM_DETAIL_DOC_ALT(alt, ...)=alt \\
+                        BOOST_FILESYSTEM_DETAIL_DOC_HIDDEN(...)=... \\
+                        BOOST_FILESYSTEM_DETAIL_DOC(...)=__VA_ARGS__ \\
+                        BOOST_NO_CXX17_DEDUCTION_GUIDES=1 \\
+                        BOOST_BITMASK(x)= \\
+                        BOOST_SYMBOL_VISIBLE= \\
+                        BOOST_FORCEINLINE=inline \\
+                        BOOST_INLINE_VARIABLE=inline \\
+                        BOOST_NOEXCEPT=noexcept \\
+                        BOOST_CONSTEXPR=constexpr \\
+                        BOOST_CXX14_CONSTEXPR=constexpr"
+        <xsl:param>boost.doxygen.detailns=detail
+#        <xsl:param>boost.doxygen.detail=implementation_
+    ;
+
+
+doxygen path_reference
+    :
+        ../../../boost/filesystem/path.hpp
+    :
+        $(doxygen_params)
+        <xsl:param>"boost.doxygen.reftitle=Path Reference"
+        <xsl:param>"boost.doxygen.refid=path"
+    ;
+
+doxygen operations_reference
+    :
+        ../../../boost/filesystem/operations.hpp
+    :
+        $(doxygen_params)
+        <xsl:param>"boost.doxygen.reftitle=Filesystem Operations"
+        <xsl:param>"boost.doxygen.refid=operations"
+    ;
 
-# Library home page: http://www.boost.org/libs/filesystem
+doxygen directory_reference
+    :
+        ../../../boost/filesystem/directory.hpp
+    :
+        $(doxygen_params)
+        <xsl:param>"boost.doxygen.reftitle=Directory Iteration"
+        <xsl:param>"boost.doxygen.refid=directory"
+    ;
 
-project
-    : requirements
-      <library>/boost/filesystem//boost_filesystem
-      <link>static
+doxygen file_status_reference
+    :
+        ../../../boost/filesystem/file_status.hpp
+    :
+        $(doxygen_params)
+        <xsl:param>"boost.doxygen.reftitle=File Status"
+        <xsl:param>"boost.doxygen.refid=file_status"
     ;
 
-exe path_table : path_table.cpp ;
-install path_table-copy : path_table : <location>. ;
+doxygen exception_reference
+    :
+        ../../../boost/filesystem/exception.hpp
+    :
+        $(doxygen_params)
+        <xsl:param>"boost.doxygen.reftitle=Exceptions"
+        <xsl:param>"boost.doxygen.refid=exceptions"
+    ;
+
+doxygen io_reference
+    :
+        ../../../boost/filesystem/cstdio.hpp
+        ../../../boost/filesystem/fstream.hpp
+    :
+        $(doxygen_params)
+        <xsl:param>"boost.doxygen.reftitle=I/O Utilities"
+        <xsl:param>"boost.doxygen.refid=io_utilities"
+    ;
+
+xml filesystem_doc
+    :
+        filesystem.qbk
+    :
+        <dependency>path_reference
+        <dependency>operations_reference
+        <dependency>directory_reference
+        <dependency>file_status_reference
+        <dependency>exception_reference
+        <dependency>io_reference
+    ;
+
+boostbook filesystem
+    :
+        filesystem_doc
+    :
+        <xsl:param>"boost.root=../../../.."
+        <xsl:param>"boost.libraries=../../../libs/libraries.htm"
+        <xsl:param>"nav.layout=none"
+        <xsl:param>"boost.image=Boost"
+        <xsl:param>"navig.graphics=1"
+        <xsl:param>"chunk.section.depth=1"
+        <xsl:param>"boost.compact.function=0"
+        <xsl:param>"boost.sort.params=0"
+        <format>pdf:<xsl:param>"boost.url.prefix=https://www.boost.org/doc/libs/release/libs/filesystem/doc/html"
+    ;
 
 ###############################################################################
 alias boostdoc ;
 explicit boostdoc ;
-alias boostrelease ;
+alias boostrelease : filesystem ;
 explicit boostrelease ;

doc/acknowledgements.qbk

@@ -0,0 +1,137 @@
+[/
+ / Copyright Andrey Semashev 2024.
+ /
+ / Distributed under the Boost Software License, Version 1.0.
+ / (See accompanying file LICENSE_1_0.txt or copy at
+ / https://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:acknowledgements Acknowledgements]
+
+[section:v1 Version 1]
+
+The Filesystem Library was designed and implemented by Beman Dawes. The original `directory_iterator` and `filesystem_error` classes
+were based on prior work from Dietmar Kühl, as modified by Jan Langer. Thomas Witt was a particular help in later stages of initial
+development. Peter Dimov and Rob Stewart made many useful suggestions and comments over a long period of time. Howard Hinnant helped
+with internationalization issues.
+
+Key [link filesystem.design.requirements design requirements] and [link filesystem.design.realities design realities] were developed
+during extensive discussions on the Boost mailing list, followed by comments on the initial implementation. Numerous helpful comments
+were then received during the Formal Review. Participants included:
+
+* Aaron Brashears
+* Alan Bellingham
+* Aleksey Gurtovoy
+* Alex Rosenberg
+* Alisdair Meredith
+* Andy Glew
+* Anthony Williams
+* Baptiste Lepilleur
+* Beman Dawes
+* Bill Kempf
+* Bill Seymour
+* Carl Daniel
+* Chris Little
+* Chuck Allison
+* Craig Henderson
+* Dan Nuffer
+* Dan'l Miller
+* Daniel Frey
+* Darin Adler
+* David Abrahams
+* David Held
+* Davlet Panech
+* Dietmar Kühl
+* Douglas Gregor
+* Dylan Nicholson
+* Ed Brey
+* Eric Jensen
+* Eric Woodruff
+* Fedder Skovgaard
+* Gary Powell
+* Gennaro Prota
+* Geoff Leyland
+* George Heintzelman
+* Giovanni Bajo
+* Glen Knowles
+* Hillel Sims
+* Howard Hinnant
+* Jaap Suter
+* James Dennett
+* Jan Langer
+* Jani Kajala
+* Jason Stewart
+* Jeff Garland
+* Jens Maurer
+* Jesse Jones
+* Jim Hyslop
+* Joel de Guzman
+* Joel Young
+* John Levon
+* John Maddock
+* John Williston
+* Jonathan Caves
+* Jonathan Biggar
+* Jurko
+* Justus Schwartz
+* Keith Burton
+* Ken Hagen
+* Kostya Altukhov
+* Mark Rodgers
+* Martin Schuerch
+* Matt Austern
+* Matthias Troyer
+* Mattias Flodin
+* Michiel Salters
+* Mickael Pointier
+* Misha Bergal
+* Neal Becker
+* Noel Yap
+* Parksie
+* Patrick Hartling
+* Pavel Vozenilek
+* Pete Becker
+* Peter Dimov
+* Rainer Deyke
+* Rene Rivera
+* Rob Lievaart
+* Rob Stewart
+* Ron Garcia
+* Ross Smith
+* Sashan
+* Steve Robbins
+* Thomas Witt
+* Tom Harris
+* Toon Knapen
+* Victor Wagner
+* Vincent Finn
+* Vladimir Prus
+* Yitzhak Sapir
+
+A lengthy discussion on the C++ committee's library reflector illuminated the "illusion of portability" problem, particularly in
+postings by PJ Plauger and Pete Becker.
+
+Walter Landry provided much help illuminating symbolic link use cases for version 1.31.0.
+
+[endsect]
+
+[section:v2 Version 2]
+
+So many people have contributed comments and bug reports that it isn't any longer possible to acknowledge them individually. That said,
+Peter Dimov and Rob Stewart need to be specially thanked for their many constructive criticisms and suggestions. Terence Wilson and
+Chris Frey contributed timing programs which helped illuminate performance issues.
+
+[endsect]
+
+[section:v3 Version 3]
+
+Peter Dimov suggested the idea of a single path class that could cope with multiple character types and encodings rather than
+a `basic_path` class template. That idea was the basis for the Version 3 redesign. Walter Landry contributed both the design
+and implementation of the `copy_any`, `copy_directory`, `copy_symlink`, and `read_symlink` functions.
+
+Thanks for comments from Robert Stewart, Zach Laine, Peter Dimov, Gregory Peele, Scott McMurray, John Bytheway, Jeff Flinn,
+Jeffery Bosboom.
+
+[endsect]
+
+[endsect]

doc/cautions.qbk

@@ -0,0 +1,60 @@
+[/
+ / Copyright Andrey Semashev 2024.
+ /
+ / Distributed under the Boost Software License, Version 1.0.
+ / (See accompanying file LICENSE_1_0.txt or copy at
+ / https://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:cautions Cautions]
+
+After reading the tutorial you can dive right into simple, script-like programs using
+the Filesystem Library! Before doing any serious work, however, there a few cautions to be aware of.
+
+[section:fs_races Effects and Postconditions not guaranteed in the presence of race-conditions]
+
+Filesystem function specifications follow the C++ Standard Library form, specifying behavior in terms of
+effects and postconditions. If a [link filesystem.reference.race_condition race-condition] exists,
+a function's postconditions may no longer be true by the time the function returns to the
+caller.
+
+The state of files and directories is often globally shared, and thus may be changed unexpectedly
+by other threads, processes, or even other computers having network access to the filesystem. As an
+example of the difficulties this can cause, note that the following asserts may fail:
+
+```
+assert(exists("foo") == exists("foo")); /*< This will fail if a non-existent "foo" comes into existence, or an
+                                            existent "foo" is removed, between the first and second call to `exists()`.
+                                            This could happen if, during the execution of the example code, another thread,
+                                            process, or computer is also performing operations in the same directory. */
+
+remove_all("foo");
+assert(!exists("foo")); /*< This will fail if between the call to `remove_all()` and the call to
+                            `exists()` a new file or directory named "foo" is created by another
+                            thread, process, or computer. */
+
+assert(is_directory("foo") == is_directory("foo")); /*< This will fail if another thread, process, or computer removes an
+                                                        existing file "foo" and then creates a directory named "foo", between the
+                                                        example code's two calls to `is_directory()`. */
+```
+
+[endsect]
+
+[section:exceptions Exceptions]
+
+Unless otherwise specified, Boost.Filesystem functions throw
+[link filesystem.reference.basic_filesystem_error-constructors `basic_filesystem_error`]
+exceptions to report failures such as I/O errors. Implementations may also use C++ Standard Library
+functions which can throw `std::bad_alloc` exceptions to report memory allocation errors. These exceptions
+may be thrown even though the error condition leading to the exception is not explicitly specified in
+the function's "Throws" paragraph.
+
+Nominally non-throwing versions are provided for [link filesystem.reference.operational-functions operational functions]
+that access the external file system, since these are often used in contexts where error codes may be
+the preferred way to report an error. Even the nominally non-throwing versions of functions will throw
+`std::bad_alloc` exceptions to report memory allocation errors. However, functions marked `noexcept` never
+throw exceptions.
+
+[endsect]
+
+[endsect]