Skip to content

Commit ad3b067

Browse files
LastiqueLastique
committed
Rewritten documentation in QuickBook and Doxygen.
1 parent 45cc448 commit ad3b067

35 files changed

Lines changed: 15793 additions & 438 deletions

‎bug/bug.cpp‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
1+
// Copyright Beman Dawes 2014
2+
// Distributed under the Boost Software License, Version 1.0.
3+
// www.boost.org/LICENSE_1_0.txt
4+
//
15
// filesystem/bug/bug.cpp
26

7+
//[bug_cpp
38
#include <boost/detail/lightweight_test_report.hpp>
49
#include <boost/filesystem.hpp>
510

@@ -13,7 +18,4 @@ int test_main(int, char*[]) // note name
1318

1419
return ::boost::report_errors(); // required
1520
}
16-
17-
// Copyright Beman Dawes 2014
18-
// Distributed under the Boost Software License, Version 1.0.
19-
// www.boost.org/LICENSE_1_0.txt
21+
//]

‎bug/index.html‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎doc/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
html
2+
*_reference.xml

‎doc/Jamfile.v2‎

Lines changed: 138 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,149 @@
1-
# Boost Filesystem Library Example Jamfile
1+
# Copyright 2024 Andrey Semashev
2+
#
3+
# Distributed under the Boost Software License, Version 1.0.
4+
# (See accompanying file LICENSE_1_0.txt or copy at
5+
# https://www.boost.org/LICENSE_1_0.txt)
26

3-
# Copyright Beman Dawes 2010
7+
using quickbook ;
8+
using boostbook ;
9+
using doxygen ;
10+
using xsltproc ;
411

5-
# Distributed under the Boost Software License, Version 1.0.
6-
# See www.boost.org/LICENSE_1_0.txt
12+
import set ;
13+
import doxygen ;
14+
import xsltproc ;
15+
import notfile ;
16+
import path ;
17+
import project ;
18+
19+
project boost/libs/filesystem/doc ;
20+
21+
local doxygen_params =
22+
<doxygen:param>RECURSIVE=YES
23+
<doxygen:param>ALPHABETICAL_INDEX=YES
24+
<doxygen:param>REPEAT_BRIEF=YES
25+
<doxygen:param>ALWAYS_DETAILED_SEC=YES
26+
<doxygen:param>BRIEF_MEMBER_DESC=NO
27+
<doxygen:param>ABBREVIATE_BRIEF=YES
28+
<doxygen:param>INHERIT_DOCS=YES
29+
<doxygen:param>HIDE_UNDOC_MEMBERS=YES
30+
<doxygen:param>HIDE_UNDOC_CLASSES=YES
31+
<doxygen:param>HIDE_SCOPE_NAMES=YES
32+
<doxygen:param>AUTOLINK_SUPPORT=YES
33+
<doxygen:param>DISTRIBUTE_GROUP_DOC=NO
34+
<doxygen:param>SUBGROUPING=NO
35+
<doxygen:param>EXTRACT_ALL=NO
36+
<doxygen:param>EXTRACT_PRIVATE=NO
37+
<doxygen:param>BUILTIN_STL_SUPPORT=YES
38+
<doxygen:param>ENABLE_PREPROCESSING=YES
39+
<doxygen:param>MACRO_EXPANSION=YES
40+
<doxygen:param>SHORT_NAMES=YES
41+
<doxygen:param>TAB_SIZE=4
42+
<doxygen:param>SOURCE_BROWSER=YES
43+
<doxygen:param>VERBATIM_HEADERS=NO
44+
# <doxygen:param>SEARCH_INCLUDES=YES
45+
# <doxygen:param>"INCLUDE_PATH=../../.."
46+
# <doxygen:param>EXCLUDE_SYMBOLS="detail detail::*"
47+
<doxygen:param>"PREDEFINED=BOOST_FILESYSTEM_DOXYGEN \\
48+
BOOST_FILESYSTEM_DECL= \\
49+
BOOST_FILESYSTEM_DETAIL_DOC_ALT(alt, ...)=alt \\
50+
BOOST_FILESYSTEM_DETAIL_DOC_HIDDEN(...)=... \\
51+
BOOST_FILESYSTEM_DETAIL_DOC(...)=__VA_ARGS__ \\
52+
BOOST_NO_CXX17_DEDUCTION_GUIDES=1 \\
53+
BOOST_BITMASK(x)= \\
54+
BOOST_SYMBOL_VISIBLE= \\
55+
BOOST_FORCEINLINE=inline \\
56+
BOOST_INLINE_VARIABLE=inline \\
57+
BOOST_NOEXCEPT=noexcept \\
58+
BOOST_CONSTEXPR=constexpr \\
59+
BOOST_CXX14_CONSTEXPR=constexpr"
60+
<xsl:param>"boost.doxygen.detailns=detail"
61+
;
62+
63+
64+
doxygen path_reference
65+
:
66+
../../../boost/filesystem/path.hpp
67+
:
68+
$(doxygen_params)
69+
<xsl:param>"boost.doxygen.reftitle=Path Reference"
70+
<xsl:param>"boost.doxygen.refid=path"
71+
;
72+
73+
doxygen operations_reference
74+
:
75+
../../../boost/filesystem/operations.hpp
76+
:
77+
$(doxygen_params)
78+
<xsl:param>"boost.doxygen.reftitle=Filesystem Operations"
79+
<xsl:param>"boost.doxygen.refid=operations"
80+
;
781

8-
# Library home page: http://www.boost.org/libs/filesystem
82+
doxygen directory_reference
83+
:
84+
../../../boost/filesystem/directory.hpp
85+
:
86+
$(doxygen_params)
87+
<xsl:param>"boost.doxygen.reftitle=Directory Iteration"
88+
<xsl:param>"boost.doxygen.refid=directory"
89+
;
990

10-
project
11-
: requirements
12-
<library>/boost/filesystem//boost_filesystem
13-
<link>static
91+
doxygen file_status_reference
92+
:
93+
../../../boost/filesystem/file_status.hpp
94+
:
95+
$(doxygen_params)
96+
<xsl:param>"boost.doxygen.reftitle=File Status"
97+
<xsl:param>"boost.doxygen.refid=file_status"
1498
;
1599

16-
exe path_table : path_table.cpp ;
17-
install path_table-copy : path_table : <location>. ;
100+
doxygen exception_reference
101+
:
102+
../../../boost/filesystem/exception.hpp
103+
:
104+
$(doxygen_params)
105+
<xsl:param>"boost.doxygen.reftitle=Exceptions"
106+
<xsl:param>"boost.doxygen.refid=exceptions"
107+
;
108+
109+
doxygen io_reference
110+
:
111+
../../../boost/filesystem/cstdio.hpp
112+
../../../boost/filesystem/fstream.hpp
113+
:
114+
$(doxygen_params)
115+
<xsl:param>"boost.doxygen.reftitle=I/O Utilities"
116+
<xsl:param>"boost.doxygen.refid=io_utilities"
117+
;
118+
119+
xml filesystem_doc
120+
:
121+
filesystem.qbk
122+
:
123+
<dependency>path_reference
124+
<dependency>operations_reference
125+
<dependency>directory_reference
126+
<dependency>file_status_reference
127+
<dependency>exception_reference
128+
<dependency>io_reference
129+
;
130+
131+
boostbook filesystem
132+
:
133+
filesystem_doc
134+
:
135+
<xsl:param>"boost.root=../../../.."
136+
<xsl:param>"boost.libraries=../../../libs/libraries.htm"
137+
<xsl:param>"nav.layout=none"
138+
<xsl:param>"boost.image=Boost"
139+
<xsl:param>"navig.graphics=1"
140+
<xsl:param>"chunk.section.depth=1"
141+
<xsl:param>"boost.compact.function=0"
142+
<format>pdf:<xsl:param>"boost.url.prefix=https://www.boost.org/doc/libs/release/libs/filesystem/doc/html"
143+
;
18144

19145
###############################################################################
20146
alias boostdoc ;
21147
explicit boostdoc ;
22-
alias boostrelease ;
148+
alias boostrelease : filesystem ;
23149
explicit boostrelease ;

‎doc/acknowledgements.qbk‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
[/
2+
/ Copyright Andrey Semashev 2024.
3+
/
4+
/ Distributed under the Boost Software License, Version 1.0.
5+
/ (See accompanying file LICENSE_1_0.txt or copy at
6+
/ https://www.boost.org/LICENSE_1_0.txt)
7+
/]
8+
9+
[section:acknowledgements Acknowledgements]
10+
11+
[section:v1 Version 1]
12+
13+
The Filesystem Library was designed and implemented by Beman Dawes. The original `directory_iterator` and `filesystem_error` classes
14+
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
15+
development. Peter Dimov and Rob Stewart made many useful suggestions and comments over a long period of time. Howard Hinnant helped
16+
with internationalization issues.
17+
18+
Key [link filesystem.design.requirements design requirements] and [link filesystem.design.realities design realities] were developed
19+
during extensive discussions on the Boost mailing list, followed by comments on the initial implementation. Numerous helpful comments
20+
were then received during the Formal Review. Participants included:
21+
22+
* Aaron Brashears
23+
* Alan Bellingham
24+
* Aleksey Gurtovoy
25+
* Alex Rosenberg
26+
* Alisdair Meredith
27+
* Andy Glew
28+
* Anthony Williams
29+
* Baptiste Lepilleur
30+
* Beman Dawes
31+
* Bill Kempf
32+
* Bill Seymour
33+
* Carl Daniel
34+
* Chris Little
35+
* Chuck Allison
36+
* Craig Henderson
37+
* Dan Nuffer
38+
* Dan'l Miller
39+
* Daniel Frey
40+
* Darin Adler
41+
* David Abrahams
42+
* David Held
43+
* Davlet Panech
44+
* Dietmar Kühl
45+
* Douglas Gregor
46+
* Dylan Nicholson
47+
* Ed Brey
48+
* Eric Jensen
49+
* Eric Woodruff
50+
* Fedder Skovgaard
51+
* Gary Powell
52+
* Gennaro Prota
53+
* Geoff Leyland
54+
* George Heintzelman
55+
* Giovanni Bajo
56+
* Glen Knowles
57+
* Hillel Sims
58+
* Howard Hinnant
59+
* Jaap Suter
60+
* James Dennett
61+
* Jan Langer
62+
* Jani Kajala
63+
* Jason Stewart
64+
* Jeff Garland
65+
* Jens Maurer
66+
* Jesse Jones
67+
* Jim Hyslop
68+
* Joel de Guzman
69+
* Joel Young
70+
* John Levon
71+
* John Maddock
72+
* John Williston
73+
* Jonathan Caves
74+
* Jonathan Biggar
75+
* Jurko
76+
* Justus Schwartz
77+
* Keith Burton
78+
* Ken Hagen
79+
* Kostya Altukhov
80+
* Mark Rodgers
81+
* Martin Schuerch
82+
* Matt Austern
83+
* Matthias Troyer
84+
* Mattias Flodin
85+
* Michiel Salters
86+
* Mickael Pointier
87+
* Misha Bergal
88+
* Neal Becker
89+
* Noel Yap
90+
* Parksie
91+
* Patrick Hartling
92+
* Pavel Vozenilek
93+
* Pete Becker
94+
* Peter Dimov
95+
* Rainer Deyke
96+
* Rene Rivera
97+
* Rob Lievaart
98+
* Rob Stewart
99+
* Ron Garcia
100+
* Ross Smith
101+
* Sashan
102+
* Steve Robbins
103+
* Thomas Witt
104+
* Tom Harris
105+
* Toon Knapen
106+
* Victor Wagner
107+
* Vincent Finn
108+
* Vladimir Prus
109+
* Yitzhak Sapir
110+
111+
A lengthy discussion on the C++ committee's library reflector illuminated the "illusion of portability" problem, particularly in
112+
postings by PJ Plauger and Pete Becker.
113+
114+
Walter Landry provided much help illuminating symbolic link use cases for version 1.31.0.
115+
116+
[endsect]
117+
118+
[section:v2 Version 2]
119+
120+
So many people have contributed comments and bug reports that it isn't any longer possible to acknowledge them individually. That said,
121+
Peter Dimov and Rob Stewart need to be specially thanked for their many constructive criticisms and suggestions. Terence Wilson and
122+
Chris Frey contributed timing programs which helped illuminate performance issues.
123+
124+
[endsect]
125+
126+
[section:v3 Version 3]
127+
128+
Peter Dimov suggested the idea of a single path class that could cope with multiple character types and encodings rather than
129+
a `basic_path` class template. That idea was the basis for the Version 3 redesign. Walter Landry contributed both the design
130+
and implementation of the `copy_any`, `copy_directory`, `copy_symlink`, and `read_symlink` functions.
131+
132+
Thanks for comments from Robert Stewart, Zach Laine, Peter Dimov, Gregory Peele, Scott McMurray, John Bytheway, Jeff Flinn,
133+
Jeffery Bosboom.
134+
135+
[endsect]
136+
137+
[endsect]

‎doc/cautions.qbk‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
[/
2+
/ Copyright Andrey Semashev 2024.
3+
/
4+
/ Distributed under the Boost Software License, Version 1.0.
5+
/ (See accompanying file LICENSE_1_0.txt or copy at
6+
/ https://www.boost.org/LICENSE_1_0.txt)
7+
/]
8+
9+
[section:cautions Cautions]
10+
11+
After reading the tutorial you can dive right into simple, script-like programs using
12+
the Filesystem Library! Before doing any serious work, however, there a few cautions to be aware of.
13+
14+
[section:fs_races Effects and Postconditions not guaranteed in the presence of race-conditions]
15+
16+
Filesystem function specifications follow the C++ Standard Library form, specifying behavior in terms of
17+
effects and postconditions. If a [link filesystem.reference.path.usage.multithreading race-condition] exists,
18+
a function's postconditions may no longer be true by the time the function returns to the
19+
caller.
20+
21+
The state of files and directories is often globally shared, and thus may be changed unexpectedly
22+
by other threads, processes, or even other computers having network access to the filesystem. As an
23+
example of the difficulties this can cause, note that the following asserts may fail:
24+
25+
```
26+
assert(exists("foo") == exists("foo")); /*< This will fail if a non-existent "foo" comes into existence, or an
27+
existent "foo" is removed, between the first and second call to `exists()`.
28+
This could happen if, during the execution of the example code, another thread,
29+
process, or computer is also performing operations in the same directory. */
30+
31+
remove_all("foo");
32+
assert(!exists("foo")); /*< This will fail if between the call to `remove_all()` and the call to
33+
`exists()` a new file or directory named "foo" is created by another
34+
thread, process, or computer. */
35+
36+
assert(is_directory("foo") == is_directory("foo")); /*< This will fail if another thread, process, or computer removes an
37+
existing file "foo" and then creates a directory named "foo", between the
38+
example code's two calls to `is_directory()`. */
39+
```
40+
41+
[endsect]
42+
43+
[section:exceptions Exceptions]
44+
45+
Unless otherwise specified, Boost.Filesystem functions throw
46+
[link filesystem.reference.basic_filesystem_error-constructors `basic_filesystem_error`]
47+
exceptions to report failures such as I/O errors. Implementations may also use C++ Standard Library
48+
functions which can throw `std::bad_alloc` exceptions to report memory allocation errors. These exceptions
49+
may be thrown even though the error condition leading to the exception is not explicitly specified in
50+
the function's "Throws" paragraph.
51+
52+
Nominally non-throwing versions are provided for [link filesystem.reference.operational-functions operational functions]
53+
that access the external file system, since these are often used in contexts where error codes may be
54+
the preferred way to report an error. Even the nominally non-throwing versions of functions will throw
55+
`std::bad_alloc` exceptions to report memory allocation errors. However, functions marked `noexcept` never
56+
throw exceptions.
57+
58+
[endsect]
59+
60+
[endsect]

0 commit comments

Comments
 (0)