Edward Diener
[...]
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