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

Subject: Re: [boost] [GSoC] [Boost.Hana] Formal review request
From: Louis Dionne (ldionne.2_at_[hidden])
Date: 2014-07-29 21:38:30

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.

> 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?

> 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?

> 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.

Regards,
Louis