Idea: concepts for template API

[petiaccja]

Just from a user perspective, the compiler errors were pretty arcane when I did not provide the right parameters to htile. htile implicitly requires all E&& elements to be derived from class element.

This is the general definition for these functions:

   template <typename... E>
   inline auto htile(E&&... elements)
   {
      using composite = array_composite<sizeof...(elements), htile_element>;
      using container = typename composite::container_type;
      composite r{};
      r = container{{ share(std::forward<E>(elements))... }};
      return r;
   }

It would be possible to add either

1. an extra template parameter

std::enable_if_t<std::conjunction_v<std::is_convertible<E&, element&>...>, int> = 0

2. a C++20 concept:

requires std::conjunction_v<std::is_convertible<E&, element&>...>

3. or a static_assert:

static_assert(std::conjunction_v<std::is_convertible<E&, element&>...>, "All arguments must be convertible to 'element'");

1. and 2) takes the function out of the overload resolution, so it trips the syntax error highlighting in IDEs right away, which is pretty helpful. 3) at least gives a more useful message on what to fix.

So I'm just throwing this idea in that it may be useful to enforce these conditions more explicitly in the interfaces.

[djowel]

So I'm just throwing this idea in that it may be useful to enforce these conditions more explicitly in the interfaces.

Makes sense, of course. The requirement is c++17 so, static_assert is the best we can do. Some classes already have the static_asserts. Some don't (yet). Would you be interested to do a PR for these? Incremental is fine too if you will.

[petiaccja]

I was thinking that if concepts are not available, enable_ifs would still be better than static_asserts, because with them the IDE catches the errors before compilation. True, the error messages will be not so clean as with static_asserts when compiled, but reading the enable_if conditions is fairly straightforward.

Who do you think is the current and future audience for the library? Would they benefit more from IDE support or somewhat cleaner compilation messages?

As for making a PR myself, I may give it a try, but I cannot promise as I have other things I'm trying to focus on. Do you perhaps have any guidance on contributing to the library? For example, a document that describes its structure and components. That would make it easier to identify these functions where adding compile time checks would be useful.

[djowel]

In due time, when c++20 becomes more commonplace, my preference is concept (to be honest I am resisting the temptation now!). In the meantime I'd prefer static_assert over enable_if. One downside with enable_if is that it tends to clutter the API with ugly code. I have no idea if current and future audiences are IDE users. I don't think there's a way to know.

Alas, there are no internal documents yet about the structure and components. For simple things like this, on 'maintenance' mode, I just plow through the code and check things that can be improved. I suppose that's what you did that landed you into the htile function, right?

[djowel]

As for making a PR myself, I may give it a try, but I cannot promise as I have other things I'm trying to focus on. Do you perhaps have any guidance on contributing to the library? For example, a document that describes its structure and components. That would make it easier to identify these functions where adding compile time checks would be useful.

Not a problem at all. We're all busy. That said, incremental PRs (say, a function here and there) would be fine too... On the other hand, a "no I'm busy" would be fine too. I just added this in my todo list anyway, and I'll get to it eventually when I go into maintenance mode.

[petiaccja]

Yeah, I agree that concepts are not a good choice for now, they would exclude too many users. I tried them however, and they are real awesome, so it got me excited. I think for now static_asserts would be nice, perhaps they can be even marked with a TODO comment and then they can be easily replaced by concepts when they become more available.

Well, I landed in the htile as I was trying to dig into why my code doesn't compile. I was providing arguments which were not subclasses of class element, however, the compiler only tells me that container cannot be constructed from the initializer list, which is not very informative. To get to the root of the issue, you have to know what constructors container has, but container is a member typedef of a specialization/alias of a templated class, meaning you have to spend a significant amount of time understanding the hierarchy of classes to realize one of your arguments was not a subclass of element. A concept/static_assert would cut this down to a few seconds for users, but is ultimately redundant and adds some extra maintenance duties for the library developers.

It fails at r = container...:

  template <typename... E>
  inline auto htile(E&&... elements)
  {
     using composite = array_composite<sizeof...(elements), htile_element>;
     using container = typename composite::container_type;
     composite r{};
     r = container{{ share(std::forward<E>(elements))... }};
     return r;
  }

While your code is undoubtedly clean and neat, the generic and templated structure makes both static (i.e. looking at code) and dynamic (i.e. looking at runtime callstacks) understanding of its workings challanging.

Perhaps these would help both users and developers:

• More specific variable names: for example, what is choice, selector, is button.down a behavior flag or the current state of the button, or why is button_function not called button_click_callback_t?
• Doxygen comments: basically a complement to variable naming where names simply cannot be long enough. It also helps to show which elements of the library (no pun intended) are public and which are internal
• Documentation to explain concepts: sharing, holding, traversal, composites, etc. -- how do they all work together? What are the steps to process an input event from the OS? How do magic things like radio buttons work?
• A list of features: while layouts are written up nicely, finding out what controls are available and how to use them is a little difficult. It's not always clear if the API calls create (that is, declare) controls, or they are something else.
• Alternatively, namespaces could be used like elements::controls::button and elements::layouts::htile to separate internal and external APIs.

Like for me right now, I would need an effective way to identify all/most functions that are used to declaratively describe the user interface, and then deciphering and patching in compile time checks is a fairly straightforward process. Also, a general understanding of the concepts makes it easier to find the right constraints for the static_asserts. Plowing through code is fairly difficult without familiarity with the library.

[djowel]

Splendid comments! Replies below...

Yeah, I agree that concepts are not a good choice for now, they would exclude too many users. I tried them however, and they are real awesome, so it got me excited. I think for now static_asserts would be nice, perhaps they can be even marked with a TODO comment and then they can be easily replaced by concepts when they become more available.

Yeah, I've been following concepts since 0x as it has undergone significant changes, from different camps. The first one "C++0x Concepts," was a lot more powerful, actually. Alas, it did not win the battle.

Well, I landed in the htile as I was trying to dig into why my code doesn't compile.

[snips]

Yeah, I understand what you mean. There will be more of this, I am sure. These are the things that are in my "todo" list that I act on as part of maintenance.

While your code is undoubtedly clean and neat, the generic and templated structure makes both static (i.e. looking at code) and dynamic (i.e. looking at runtime callstacks) understanding of its workings challanging.

Understood. My main goal now is to have a complete set of docs. It's kinda tricky though as the code is also undergoing evolution.

Perhaps these would help both users and developers:

• More specific variable names: for example, what is choice, selector, is button.down a behavior flag or the current state of the button, or why is button_function not called button_click_callback_t?

Aren't those a matter of documentation? I'm not sure I am inclined to go into a 'bike-shed' discussion on names though.

• Doxygen comments: basically a complement to variable naming where names simply cannot be long enough. It also helps to show which elements of the library (no pun intended) are public and which are internal

TBH, I dislike doxygen. I haven't seen a usable doxygen generated docs for a generic, modern c++ library. If you know one, I'd like to see it. I'm open to be convinced.

• Documentation to explain concepts: sharing, holding, traversal, composites, etc. -- how do they all work together? What are the steps to process an input event from the OS? How do magic things like radio buttons work?

Absolutely! As stated in the main page: "Documentation is work in progress." I work on it regularly, at least a few hours a week. Well written documentation, like code, is a craft, takes time.

• A list of features: while layouts are written up nicely, finding out what controls are available and how to use them is a little difficult. It's not always clear if the API calls create (that is, declare) controls, or they are something else.

Absolutely!

• Alternatively, namespaces could be used like elements::controls::button and elements::layouts::htile to separate internal and external APIs.

Interesting idea. Noted! I'll ponder on this. This might also solve some class vs. (factory)function dilemma. E.g. class button_element vs. button function.

Like for me right now, I would need an effective way to identify all/most functions that are used to declaratively describe the user interface, and then deciphering and patching in compile time checks is a fairly straightforward process. Also, a general understanding of the concepts makes it easier to find the right constraints for the static_asserts. Plowing through code is fairly difficult without familiarity with the library.

Yes, I understand. I'll see if I can get something up in the coming days. If you liked the layouts docs, that's my idea of what documentation should look like. It takes time to craft such documentation, but I think it is very much worth it in the end.

[petiaccja]

Understood. My main goal now is to have a complete set of docs. It's kinda tricky though as the code is also undergoing evolution.

Absolutely! As stated in the main page: "Documentation is work in progress." I work on it regularly, at least a few hours a week. Well written documentation, like code, is a craft, takes time.

I totally agree, writing quality documentation is neither easy nor fast, especially with evolving code.

If you liked the layouts docs

Yes, definitely. The layouts doc was very helpful, and a similar one for controls would be much appreciated.

More specific variable names: for example, what is choice, selector, is button.down a behavior flag or the current state of the button, or why is button_function not called button_click_callback_t?

Aren't those a matter of documentation? I'm not sure I am inclined to go into a 'bike-shed' discussion on names though.

Good question. Variable names are a form of documentation themselves, so the more specific they are, the less "real" documentation you have to write and the less people have to look at the documentation. There is much talk about fully "self-documenting code", but I'm not sure if that exists in real life, or if it's even desirable. Nevertheless, I think a little more verbosity pays off in the end: regarding the button_click_callback (with or without suffix _t) vs. button_function case, it clears up what it's for exactly, and spares you from the headache when you later have to add for example button_hover_callback which has a different signature. (I brought this one up only for illustration purposes, I have no intention to discuss particular names one-by-one either.)

TBH, I dislike doxygen. I haven't seen a usable doxygen generated docs for a generic, modern c++ library. If you know one, I'd like to see it. I'm open to be convinced.

SFML is not really generic, but I think its documentation is pretty good. Then there is also Eigen, which is a fully templated library. The docs of LEMON also proved pretty useful to me.

I think that doxygen comments have their place: they are something between variable names and user guides. A small extra piece of information attached to a variable that describes what the variable name could not capture. Doxygen comments won't help you understand the general use of the library, but can help clear up its individual pieces. Also, it's very handy that you have the docs right next to the code, without searching for them or leaving the IDE.

As an example, here, people know they want shear, and they will find the shear transform. However, the variable names really only make sense with the extra documentation, because they are hard to unambiguously describe in just 2-3 words.

/// <summary> Creates a shear matrix. </summary>
/// <param name="slope"> Strength of the shear. </param>
/// <param name="principalAxis"> Points are moved along this axis. </param>
/// <param name="modulatorAxis"> The displacement of points is proportional to this coordinate's value. </param>
/// <remarks> The formula for displacement along the pricipal axis is
///		<paramref name="slope"/>&ast;pos[<paramref name="modulatorAxis"/>]. </remarks>
template <class T>
auto Shear(T slope, int principalAxis, int modulatorAxis) {
	return ShearBuilder(slope, principalAxis, modulatorAxis);
}

I used to dislike doxygen, too, but I kinda learned to appreciate it. I prefer the C#-style XML comments though, but doxygen can handle those as well.

[djowel]

Understood. My main goal now is to have a complete set of docs. It's kinda tricky though as the code is also undergoing evolution.

Absolutely! As stated in the main page: "Documentation is work in progress." I work on it regularly, at least a few hours a week. Well written documentation, like code, is a craft, takes time.

I totally agree, writing quality documentation is neither easy nor fast, especially with evolving code.

If you liked the layouts docs

Yes, definitely. The layouts doc was very helpful, and a similar one for controls would be much appreciated.

More specific variable names: for example, what is choice, selector, is button.down a behavior flag or the current state of the button, or why is button_function not called button_click_callback_t?

Aren't those a matter of documentation? I'm not sure I am inclined to go into a 'bike-shed' discussion on names though.

Good question. Variable names are a form of documentation themselves, so the more specific they are, the less "real" documentation you have to write and the less people have to look at the documentation. There is much talk about fully "self-documenting code", but I'm not sure if that exists in real life, or if it's even desirable. Nevertheless, I think a little more verbosity pays off in the end: regarding the button_click_callback (with or without suffix _t) vs. button_function case, it clears up what it's for exactly, and spares you from the headache when you later have to add for example button_hover_callback which has a different signature. (I brought this one up only for illustration purposes, I have no intention to discuss particular names one-by-one either.)

I prefer *_type than *_t, although granted, _t is quite common, esp. in std. In this particular example, I'm probably OK with button_callback_type. "click" is unnecessary info unless you have other callbacks too; there is only one. There's aesthetics in naming too, which is rather subjective, I'm sure you agree.

I agree with your reasoning though. Moreover, there are other factors at play too, such as consistency. I'm pretty sure I haven't paid enough attention to naming yet that I'm certain I've violated some. Naming too is not easy and many times, I get into that state where I say to myself: "this will do for now, I need to finish". That state of naming things is often at odds with the side of your brain involved with coding.

Here's what I can do: How about starting with a set of naming guidelines (that includes the namespace suggestions)?
We can discuss the guidelines, until we reach something reasonable, then adjust the names based on it.

TBH, I dislike doxygen. I haven't seen a usable doxygen generated docs for a generic, modern c++ library. If you know one, I'd like to see it. I'm open to be convinced.

SFML is not really generic, but I think its documentation is pretty good. Then there is also Eigen, which is a fully templated library. The docs of LEMON also proved pretty useful to me.

[snips]

I'm not ready to go there yet. I guess I am too biased. Take Eigen, for example. What makes it good IMO is the proper documentation before the "reference" starting with Class List. But that documentation proper need not be in doxygen at all. I took out a random item in the Class List and I get this:

https://bit.ly/2VkCNw8

My instant reaction is... Gak!

[djowel]

I'm not ready to go there yet. I guess I am too biased. Take Eigen, for example. What makes it good IMO is the proper documentation before the "reference" starting with Class List. But that documentation proper need not be in doxygen at all. I took out a random item in the Class List and I get this:

https://bit.ly/2VkCNw8

My instant reaction is... Gak!

This one is usable though:

http://lemon.cs.elte.hu/pub/doc/1.3.1/a00169.html

[djowel]

This one is usable though:

http://lemon.cs.elte.hu/pub/doc/1.3.1/a00169.html

But I am still unsure. If you look at the layout docs, (and some of my Boost projects, e.g. Fusion), you will notice the style based on concepts, expressions and expression semantics, instead of function signatures. Here's an example in Fusion:

https://www.boost.org/doc/libs/1_73_0/libs/fusion/doc/html/fusion/container/vector.html

This style of documentation is not possible using doxygen. That is the style of documentation I will be aiming for, when the API stabilizes. For now, I am starting with generic concepts.

[petiaccja]

I prefer *_type than *_t, although granted, _t is quite common, esp. in std.

I think consistency is what matters here, otherwise both work perfectly fine.

I agree with your reasoning though. Moreover, there are other factors at play too, such as consistency. I'm pretty sure I haven't paid enough attention to naming yet that I'm certain I've violated some. Naming too is not easy and many times, I get into that state where I say to myself: "this will do for now, I need to finish". That state of naming things is often at odds with the side of your brain involved with coding.

Fortunately, these days, there are great refactoring tools, so renaming a not-so-perfect variable is easy. A weaker variable name only gets problematic when the name is in the public interface, because changing it would break users' code. I often just rename things when I'm reading or modifying existing code, because the right name does not always pop into my mind right away. I think this kind of renaming is an important part of maintenance and refactoring, so I was really only trying to provide some feedback and give a reminder.

Here's what I can do: How about starting with a set of naming guidelines (that includes the namespace suggestions)?
We can discuss the guidelines, until we reach something reasonable, then adjust the names based on it.

That's a very good idea!

I really miss having a .clang-format file in elements. Modern dev tools integrate it nicely, and the formatting of code for PRs could also be checked in CI.

For one of my projects I made a short table for names based on the options in ReSharper. As you said, however, the content of the variable names is very subjective and dependent on context, so I don't think much more than "be descriptive" can be said. Of course, some rules like "always suffix exceptions with ...Error" and mandating callback types of controls to be named in a specific way is reasonable.

[djowel]

For one of my projects I made a short table for names based on the options in ReSharper. As you said, however, the content of the variable names is very subjective and dependent on context, so I don't think much more than "be descriptive" can be said. Of course, some rules like "always suffix exceptions with ...Error" and mandating callback types of controls to be named in a specific way is reasonable.

Naming style is simple to begin with: I just use the stl/boost naming scheme: CamelCase on template type parameters and concepts, lower_plus_underscore everywhere else, PREFIX_UPPER_UNDERSCORE on preprocessor names, where PREFIX is the main namespace, e.g. this case CYCFI.

I'm with you: consistency is the most important factor here, so *_type is my preference. I added the 'naming guidelines' in my todo list. I'll get to it when I am on documentation mode.

[redtide]

https://www.boost.org/doc/libs/1_73_0/libs/fusion/doc/html/fusion/container/vector.html

This style of documentation is not possible using doxygen. That is the style of documentation I will be aiming for, when the API stabilizes. For now, I am starting with generic concepts.

That looks like something you could do with Jekyll/markdown, so it would be part of the website (and also readable offline from the md source as well).

[djowel]

That looks like something you could do with Jekyll/markdown, so it would be part of the website (and also readable offline from the md source as well).

I am already using Jekyll/markdown. Example: http://cycfi.github.io/elements/layout

[redtide]

Ah OK, I thought you were searching for another solution specific for API documentation :D