[RFC] Inline the nullary/unary/star type abbreviations

[Armael]

I would like to gather comments about whether people think it would be a good
idea to inline the nullary/unary/star type abbreviations.

I personally would like this to happen (and would be willing to submit a PR). I
believe these abbreviations greatly contribute in the feeling of "types are
unreadable" tyxml users may experience; and I believe fixing this is just a
matter of inlining them.

• I would argue that the names "nullary", "unary" and "star" only have a chance
  to make sense for people familiar with compsci. So I wouldn't say that they
  are self-explanatory.

• When trying out a new library, I usually type the names of functions in utop
  to get their types, and try to understand how to use them. Typing
  Tyxml.Html.div in utop and getting a type that uses star is not helpful
  and a bit frustrating.

  Even now that I know tyxml works, I do not try to decipher the star types; I
  just learnt to ignore the types and try to follow the common patterns. But
  sometimes you really need to look at the types, e.g. for img which has extra
  labeled arguments. It would be much better to be able to directly look at the
  types and understand how to use the functions.

• Using merlin for following the indirections and expanding the type
  abbreviations does not really work, as it also expands the variants
  abbreviations, producing an enormous and even more unreadable type.

Thoughts?

[vasilisp]

I understand your concerns. But at the same time I think types like these are useful for forcing us to do things in a uniform way (and document the uniformity). Possible remedies:

• Root for some kind of "type inlining" annotations that can be read by Ocamldoc, Merlin, the toplevel, etc. Clearly not trivial. Is there any similar proposal?
• Friendlier names. The question is whether a particular combinator accepts zero, one, or (a list of) many children. Put zero/one/many in the names?
• Encourage new users to use the PPX.

[Armael]

I understand your concerns. But at the same time I think types like these are
useful for forcing us to do things in a uniform way (and document the
uniformity).

Yes, I understand that there is a tradeoff here. But personally I would weight
on the side of a slight occasional maintenance burden (adding new html tags
should not happen that often?), instead of constant, systematic pain for users.

Encourage new users to use the PPX.

In the current state of things, I do not think it is possible to use the PPX in
a non-trivial way without knowing the underlying tyxml functions, and how they
are typed.

This constatation (and the present RFC) comes from a recent experience, where I
introduced tyxml to a friend. To give a bit of context, this friend is seasoned
in front-end development, is motivated, drank the ocaml kool-aid, but at the
moment is only an ocaml beginner.

I started by only introducing him to the PPX. The PPX is great for writing large
chunks of html, plugging maybe one thing in the middle. On that aspect it works
quite well.

However, my friend quickly wanted to move to writing reusable UI components, and
build the final page using them — which sounds like a pretty reasonable thing to
do. Using the PPX for that wasn't so pleasant.

Say, for example, we define a component that contains an <input>. The
component will assign CSS classes for the input, and take an (optional)
parameter for other attributes that we may want to assign to it. Using the PPX,
we are not able to give these extra attributes using an anti-quotation, while
using the PPX syntax for the class attributes. As far as I know, there is no
PPX equivalent for input ~a:([a_class ["foo"; "bar"]; attr1] @ extra_attrs) ().
Due to a current limitation, it is also not possible to provide extra classes using an
anti-quotation.

And even then, these extra attributes given to the component will have to be
passed using the tyxml attribute functions a_*; which is a first step in the
non-PPX world. Similarly, to pass extra classes, one has to do something like
[%html {| <input class="|} ["foo"; "bar"] @ other_classes {|"/> |}] which also
requires some knowledge of how the underlying a_class works. Filling the
anti-quotations of html tag bodies also somewhat requires to know that an OCaml
list should be there, and use the OCaml syntax for lists. Typing errors can only
be really be understood knowing the underlying tyxml functions and their types.

Essentially, the PPX syntax is not as powerful as the combinators, and you end
up anyway in a situation where the PPX is only used to avoid calling the tyxml
function directly, but without avoiding the typing difficulties, and with wayyy uglier
syntax.

My conclusion was that the PPX, in its current state at least, is a nice
addition to the tyxml combinators, can be useful, but does not spares from
knowing the tyxml combinators and understanding their types — hence the present
proposition, to hopefully make that a bit easier.

[Drup]

I agree, it's not possible to use only the html syntax at the moment. I have plans to improve that (when I have time to dedicate to tyxml again :p).

That being said, @vasilisp's argument about uniformity is extremely important, so just abandoning the aliases is not a great idea.
There are ways to perform the inlining directly in the module system (using tricks with destructive substitution such as include sig ... end with type .. := ...) but they would probably make the code look worse and are usually very ocamldoc-unfriendly.

I'm very favorable to finding better names and improving the documentation, though. So that could be a useful actionable first step before trying out more radical changes.

[Armael]

In this context, ocaml/ocaml#792 seems to be a showstopper for tricks with destructive substitutions.