Larry Evans
On 06/06/2015 10:21 AM, Louis Dionne wrote:> Larry Evans
writes: [...]
BTW, I've found another minor problem with the documentation. At the momment, I find it easier to report these as I find them. Should I email you directly or post to the boost.devel list?
First, thanks for reporting these problems so I can make the documentation better. The simplest way for me would be that you open a GitHub issue [1] for problems of this kind. It takes a couple more seconds to write than an email, but it allows me to keep track of things when the number of comments becomes higher (will probably happen during the review). If you don't have a GitHub account, an email to the list works fine for me, since it leaves a public track of what was done and why. This might help reduce the number of duplicate issues reported since I can't update the project during the formal review.
Any, the minor problem is here:
http://ldionne.com/hana/structboost_1_1hana_1_1Tuple.html
which contains:
Synopsis of methods template<> constexpr auto make< Tuple > Create a Tuple containing the given objects. More...
However, there are no 'given objects' in the above. This requires the reader to puzzle over what's meant. The reader finds a hint further down in the Methods section which contains:
[...]
I changed the brief description to something that does not require seeing the `xs...`.
[...]
The documentation would be clearer if Tuple were described as a some sort of Tag "designating" a type similar to std::tuple and the link to Tuple sent the brower to a page with this description.
I modified the tutorial to explain better what are those types with a capital letter. You can find that explanation in the section on container types [2]. Also the reference documentation for each tag (Tuple, Range, etc..) now introduces the type as being a "tag" representing an object rather than as being the type of an actual object. For example, you can see the updated documentation for Tuple at [3]. Please let me know if you think those changes are enough to make things clear, or if you feel I'm still leaving readers confused. Regards, Louis [1]: https://github.com/ldionne/hana/issues [2]: http://ldionne.com/hana/#tutorial-containers-types [3]: http://ldionne.com/hana/structboost_1_1hana_1_1Tuple.html