On 4 Aug 2015 at 12:40, Gavin Lambert wrote:
Fixed. Each reference page now links to related types too.
They still seem to be missing on the function reference pages (I checked https://boostgsoc13.github.io/boost.afio/doc/html/afio/reference/functions/e...), which is probably where they'd be the most useful.
It's actually there, it's just the docs generation tooling has collapsed the paragraphs into a single large paragraph. I'll look into a workaround after I've ported AFIO onto the new APIBind based multi-abi implementation of Boost.Monad.
I'm used to the style of the Boost.Asio docs (eg. http://www.boost.org/doc/libs/1_58_0/doc/html/boost_asio/reference/async_rea...), where all the types are linked directly in the method description. (Of course, mostly they're templates, but still...)
I don't think the Boost.Geometry doxygen to qbk tool AFIO uses can do this. For Boost.Monad I'm sticking to a pure doxygen solution. I've wasted a lot of blood and sweat for little gain on AFIO's BoostBook documentation, and doxygen I think is a much more complete documentation tool than it once used to be. It would be really great if someone could skin doxygen to output something very close to BoostBook's output as I find doxygen's default HTML output pretty awful, but I suspect many of us will need to adopt doxygen first to generate the pressue for someone to do the skinning work.
I would prefer to not report something as a symlink when target() won't work with it. So you now have an additional stat_t flag called st_reparse_point which is always the FILE_ATTRIBUTE_REPARSE_POINT flag.
I guess that depends on usage cases -- if it's most common to write code like if (type() == symlink_file) { do something with target(); } then you have a point. Although code that has sufficient error checking should be able to cope with the idea of a symlink that has an unreadable target.
But it seems odd to me to claim that a file is *not* a symlink just because you're told that it's a type of symlink that you don't know how to read.
I'd like to think AFIO's symlinks are "POSIX(-y) symlinks".
Having said that, I don't know how common custom symlinks are in the wild, or if they even exist at all.
AFIO is a bit caught here too actually. If you're enumerating a directory you have no easy way of disambiguating between a symlink to a directory and a symlink to a file. You basically have to try opening it as a directory, and if it errors out you then open it as a file.
Windows does supply what kind of symlink it is without additional syscalls, but POSIX does not. You'd have to do two syscalls per entry to disambiguate which is very costly for something so niche.
Perhaps rather than just having symlink_file, Filesystem should have symlink_file, symlink_directory, and symlink_entry? POSIX would return the latter (indicating that it's unknown whether it's a file or directory) while Windows would return one of the first two. This would still allow code to be written in a reasonably platform-independent manner.
Another option might be for stat_t to have a field that contains the OS-native flags, so that on Windows the DIRECTORY flag could be examined directly. This might also allow for other esoteric attributes (COMPRESSED, ENCRYPTED, NOT_CONTENT_INDEXED, etc) to be inspected/set as desired, although that's probably more useful in Filesystem rather than AFIO. Although I think this is uglier than the above for the enumeration case.
Given the Filesystem TS has shipped, I'd say that moment has passed. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/