On 7/29/2014 9:38 PM, Louis Dionne wrote:
Edward Diener
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.