[string_algo] Documentation Complaint
Wow, I found this documentation hard to use! I wanted to translate various 1-character substrings into new strings, e.g. translate the TAB character ('\t') to its textual escaped representation "\\t", and I went looking for an algorithm to do it. After 5 minutes of searching, I *think* the algorithm isn't there, but I'm still not sure. I nearly went blind (well, not really, but it felt that way) looking at http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/reference.html#hea... because there's no vertical whitespace. More importantly, there's *no description of what any of these algorithms actually do*! ... calming down ... Heh, very terse descriptions are in the "Quick Reference": http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/quickref.html These might be good enough for me, but I always figure I'm going to get complete detail from the non-quick reference, and this one is just a dump of all the declarations, so I had to go around in a big circle and begin writing this documentation complaint before I found it. Can this situation be improved? -- Dave Abrahams BoostPro Computing Software Development Training http://www.boostpro.com Clang/LLVM/EDG Compilers C++ Boost
On 01/11/12 15:33, Dave Abrahams wrote:
Wow, I found this documentation hard to use!
I wanted to translate various 1-character substrings into new strings, e.g. translate the TAB character ('\t') to its textual escaped representation "\\t", and I went looking for an algorithm to do it.
After 5 minutes of searching, I *think* the algorithm isn't there, but I'm still not sure.
I think replace_all_copy will do it <http://www.boost.org/doc/libs/1_51_0/doc/html/boost/algorithm/replace_all_copy.html> but it's not specifically targeted at replacing single characters, so may perform worse and/or be more cumbersome to use than something that was. Also, it only replaces one thing at a time. If you wanted to replace many different characters in one pass then you can use <http://www.boost.org/doc/libs/1_51_0/doc/html/boost/algorithm/find_format_copy.html>, but it will be quite cumbersome. (And, to add to your complaints: I wish the docs for that function linked to the docs for the Finder and Formatter concepts!).
I nearly went blind (well, not really, but it felt that way) looking at http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/reference.html#hea... because there's no vertical whitespace. More importantly, there's *no description of what any of these algorithms actually do*!
Did you notice that you can click on the function names to get more detailed info? This isn't wonderful for finding the algorithm you want, but there *is* a description of the algorithms, and the quick reference is there for browsing purposes.
.... calming down ...
Heh, very terse descriptions are in the "Quick Reference": http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/quickref.html These might be good enough for me, but I always figure I'm going to get complete detail from the non-quick reference, and this one is just a dump of all the declarations, so I had to go around in a big circle and begin writing this documentation complaint before I found it.
Can this situation be improved?
on Thu Nov 01 2012, John Bytheway <jbytheway+boost-AT-gmail.com> wrote:
On 01/11/12 15:33, Dave Abrahams wrote:
Wow, I found this documentation hard to use!
I wanted to translate various 1-character substrings into new strings, e.g. translate the TAB character ('\t') to its textual escaped representation "\\t", and I went looking for an algorithm to do it.
After 5 minutes of searching, I *think* the algorithm isn't there, but I'm still not sure.
I think replace_all_copy will do it <http://www.boost.org/doc/libs/1_51_0/doc/html/boost/algorithm/replace_all_copy.html> but it's not specifically targeted at replacing single characters, so may perform worse and/or be more cumbersome to use than something that was.
Also, it only replaces one thing at a time. If you wanted to replace many different characters in one pass then you can use <http://www.boost.org/doc/libs/1_51_0/doc/html/boost/algorithm/find_format_copy.html>, but it will be quite cumbersome.
Actually find_format_all_copy. This took me hours to get right but it's at least 75% phoenix's fault ;-) #+begin_src c++ using namespace boost::phoenix::placeholders; using namespace boost::phoenix; using namespace boost::phoenix::local_names; static const char chars_to_escape[] = "\\/\"\b\f\n\r\t"; static const char repl_chars[] = "\\/\"bfnrt"; boost::find_format_all_copy( rep, boost::token_finder(boost::is_any_of(chars_to_escape)), let ( _c = find(boost::as_array(chars_to_escape), arg1[0]) )[ string("\\") + val(repl_chars)[_c - &chars_to_escape[0]] ] ) #+end_src
(And, to add to your complaints: I wish the docs for that function linked to the docs for the Finder and Formatter concepts!).
Yes! Everywhere they're mentioned, they should be links!
I nearly went blind (well, not really, but it felt that way) looking at http://www.boost.org/doc/libs/1_51_0/doc/html/string_algo/reference.html#hea... because there's no vertical whitespace. More importantly, there's *no description of what any of these algorithms actually do*!
Did you notice that you can click on the function names to get more detailed info?
Not until long after I wrote the email.
This isn't wonderful for finding the algorithm you want, but there *is* a description of the algorithms, and the quick reference is there for browsing purposes.
Yeah, I eventually figured out how to use the docs. When we write docs, we should do more to help people who are working under pressure, though. Accessibility is really important. -- Dave Abrahams BoostPro Computing Software Development Training http://www.boostpro.com Clang/LLVM/EDG Compilers C++ Boost
participants (2)
-
Dave Abrahams -
John Bytheway