Re: [boost] [Filesystem V3] Filesystem Version 3 beta 1 available for download and comment

Subject: Re: [boost] [Filesystem V3] Filesystem Version 3 beta 1 available for download and comment
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2010-02-19 11:23:49

Beman Dawes wrote:
>
> The documentation can be viewed at
> http://mysite.verizon.net/beman/v3/index.htm

Comments on the tutorial:

Very nicely written.  You answered questions that arose as you went along as if you were in my head!

§ Reporting the size of a file

Typo: "file_size  function returns an uintmax_t"

   s/an/a/

§ Using status queries to determine file existence and type

The code shown for tut2.cpp uses what appears to be inconsistent whitespace inside parentheses.  Perhaps your style is to add whitespaces inside parentheses in conditionals, but it looks odd to me.

§ Directory iteration

You write, "A directory_entry contains a path and symlink/non-symlink resolving file_status caches, and can be passed to path arguments in function calls."  I don't understand that.  What are "symlink/non-symlink resolving file_status caches?"  Split the two parts into separate sentences for clarity.

tut3.cpp should not create a default constructed directory_iterator each iteration (even if the optimizer could hoist it out of the loop):

   for (directory_iterator it(p), end; it != end; ++it)

Perhaps it would be better to use an ostream_iterator.

§ Class path: Constructors

In tut5.cpp, you commented out two blocks that wouldn't preclude the following two, so why not leave them uncommented?

§ Class path: Generic format vs. Native format

It looks like the bold attribute was left on in the beginning of the first paragraph.

Typo: "If a drive specified or a backslash appears"

   s/specified/specifier/ (I guess)

§ Class path: Iterators, observers, composition, decomposition, and query

Clarification: "We will only show the output lines we are interested in at the moment."

   s/at the moment/at each step/

The path_info.cpp element loop also evaluates the end iterator each iteration.

Typo: "Let's look at some at the output from the a slightly different example:"

   s/the a/a/

Typo: In the final Linux output box of this section, the last argument to ./path_info is "baz.txt" but the program output suggests that it should be "baa.txt."

§ Error reporting

Clarification: "...and that's why most Boost.Filesystem operational functions come in two flavors."

   s/functions come/functions now come/

Clarification: "...by setting the ec argument..."

   s/the ec/that/ (there's no signature visible to confirm that "ec" is the name of the mentioned system::error_code & argument)

_______________________
Other Issues

There's concern over the term, "stem," expressed by others and me.  Did you consider just "name?"  I suppose that's too close to "filename," but "stem" is really odd and we should find something better.  I think it is easier to explain and remember the difference between "filename" and "name" than to remember the odd meaning of "stem" for a path.  That is, with "name," a pathname is a (possibly empty) path plus a filename, where a filename is comprised of a name and an optional extension.

Finally, you use the term "observer" in the path class in an odd way.  Those functions are accessors.  "Observer" makes me think of MVC, signals/slots, etc.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.