Re: [boost] [GSoC] [Boost.Hana] Formal review request

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Edward Diener (eldiener_at_[hidden])
Date: 2014-07-29 23:47:47

On 7/29/2014 9:38 PM, Louis Dionne wrote:
> Edward Diener <eldiener <at> tropicsoft.com> writes:
>
>>
>> [...]
>>
>> Please consider also that you are using terminology in the present
>> documentation which does not relate to C++ very well, although it may
>> relate to Haskell for all I know. If you rework the documentation please
>> use C++ terminology for things. As an example you referred to Type<T> as
>> an object when in C++ it is a class.
>
> I am confused; `Type<T>` does not exist in Hana, so I doubt I mention it
> anywhere unless I made an error. There's `type<T>`, which is a variable
> template, and `Type`, which is a C++ struct.

Yes it is 'type<t>' and not 'Type<t>'. But...

"First, type is a variable template, and type<T> is an object 
representing the C++ type T."

The syntax 'type<T>' normally means a class in C++.

>
>
>> You also refer to type classes and data classes but C++ has no specific
>> meaning for either of those terms.
>
> What did people say when they first heard about:
>    - Proto transforms
>    - MPL metafunctions / metafunction classes
>    - MPL/Fusion tags
>    - any domain-specific term introduced in a library (Spirit has a lot of them)
>
> Surely C++ had no specific meaning for any of those terms before they were
> introduced. With each library comes some terminology, and "type class" and
> "data type" are just that; new concepts for which names had to be chosen.
>
> That being said, type classes feel like C++ concepts and data types feel
> like Fusion/MPL tags, so I'll seriously consider renaming them to that if
> it can make people happier. I'm a bit worried about renaming "type classes"
> to "concepts" though, as it could lead to confusion. What do you think?

I have no objection  what you call them. I just felt that you should 
explain them as thoroughly as you feel possible ( remember you may know 
what you have designed but to others this is new ground ) before 
examples and not after.

>
>
>> Also while it is useful to give syntactical examples you should explain
>> what is occurring in C++ and not in some hypothetical Haskell-like
>> functional programming language which a C++ programmer does not know.
>> In other words no matter how brilliant or clever your library or your
>> constructs are, you need to explain what functionality does what things
>> and not just that some syntax does something but another similar syntax
>> does something else entirely.
>
> Are you refering to something specific in the current documentation, or
> is this just a general advice?

General advice. It mainly reflects that your method of explaining the 
conceptual elements of your syntax is very difficult for me, but may be 
welcomed by most others. I am just mentally incapable of understanding 
syntactical examples before I understand thoroughly the conceptual 
elements which the example is about.

I will reread the doc again to see if I can get anywhere. Thanks for 
your efforts !

>
>
>> Because in actual use if a user of your library chooses to use some syntax,
>> without understanding what the underlying functionality actually accomplishes,
>> it is way too easy to do the wrong thing in more complicated scenarios than
>> what your examples provide.