Re: [boost] [hana]Tuple doc a bit confusing (was Re: [hana]missing link on http://ldionne.com/hana/index.html#tutorial-integral

Subject: Re: [boost] [hana]Tuple doc a bit confusing (was Re: [hana]missing link on http://ldionne.com/hana/index.html#tutorial-integral
From: Louis Dionne (ldionne.2_at_[hidden])
Date: 2015-06-07 16:36:14

Larry Evans <cppljevans <at> suddenlink.net> writes:

>
> On 06/06/2015 10:21 AM, Louis Dionne wrote:> Larry Evans <cppljevans
> <at> suddenlink.net> 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