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: Beman Dawes (bdawes_at_[hidden])
Date: 2010-02-22 08:04:36

On Fri, Feb 19, 2010 at 11:23 AM, Stewart, Robert
<Robert.Stewart_at_[hidden]> wrote:
> 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!

That is really good to hear! I put a lot of hours into the tutorial
trying to achieve that effect.

>
> § Reporting the size of a file
>
> Typo: "file_size  function returns an uintmax_t"
>
>   s/an/a/

Fixed.

> § 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.

Ouch... I changed my style from whitespace to no whitespace in the
middle of the project, and failed to apply the change uniformly to the
tutorial programs.

Fixed.

> § 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?"

That's really an implementation detail, so I changed to sentence to
just say "A directory_entry object contains a path and file_status
information."

 > Split the two parts into separate sentences for clarity.

Done.

> 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.

Done.

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

Changed.

> § Class path: Generic format vs. Native format
>
> It looks like the bold attribute was left on in the beginning of the first paragraph.

Fixed.

> Typo: "If a drive specified or a backslash appears"
>
>   s/specified/specifier/ (I guess)

Fixed.

> § 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/

Changed.

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

Fixed.

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

Fixed.

> 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."

Fixed.

> § 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)

Section reworked for greater clarity. Links added to reference documentation.

> _______________________
> 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.

In 2008 we already had several very lengthy discussions of names in
this area, and changed several including to improve clarity.

>
> 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.

The "observer" terminology comes from the standard library. Since the
reference documentation is basically what will be proposed for TR2,
I'd really like to keep it aligned with the standard library's
terminology.

Thanks very much for your careful reading of the tutorial, and your
many suggestions and corrections. They should all be reflected in beta
2.

--Beman