ocsigen / ocsigen/tyxml

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

Open
#177 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement typing
Dominant language
OCaml
Stars
179
Forks
63
Avg merge
5h
Merged PRs (30d)
22

Description

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?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read lib/html_sigs.mli around line 107, then inspect Tyxml.Html.div and img in utop to see how nullary, unary, and star affect the exposed types. Review the existing comments and the reported Merlin behavior before determining whether the RFC has enough agreement to proceed. Done means a maintainer-approved decision and scope for the proposed type-abbreviation change.

Written by the indexing model from the issue text.

Assessment

Tech stack
ocaml
Domain
developer-experience
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.