Package docs nit pick - index of functions, parameter names

Learn
1

When browsing the docs for a package, I wish I could see the parameter names, not just the parameter types.

When browsing the functions in a module, I wish there was a sticky menu with a list of function names in the module.

1 Like
2

You might like https://elm.dmy.fr/. It doesn’t have everything you’re asking for but it’s does have a lot of extras like: dark mode, better mobile support, shareable searches, you can search for " " within a module and it’ll show you all functions, and probably more I’m forgetting about.

2 Likes
3

The " " is perfect!

I am just looking for parameter names, if anybody knows of any alternative website that manages to show those. I suspect it will require a core change to how documentation is generated, so alternative front ends would not be able to help.

1 Like
4

A little bit of speculation on my part, but I don’t think showing the names of arguments makes sense, unless you have support for renaming arguments locally. E.g. given a module

module Vector2 exposing (..)

type Vector2 = Vector2 Float Float

create : Float -> Float -> Vector2
create = Vector2


new : Float -> Float -> Vector2
new x_ y_ = Vector2 x_ y_

x : Vector2 -> Float
x (Vector2 x_) = x_
  • What would be the name of the arguments in create?
  • For new, would you want the arguments to read as x and y, or x_ and y_? We can’t use the variable x locally because it’s also the name of a function.
  • What would the name of the argument be in the function x?

These are just a few of the examples I think of off hand, but they make it difficult to answer what names would be exposed in the docs.

If I had to guess, my guess is that you’re running into a confusing function like the create one I defined above. In a case like that I’d argue that it’s possibly a poor function definition that should instead be written like

createBetter : { x  : Float, y : Float } -> Vector2
createBetter options = Vector2 options.x options.y

or possibly like

type alias X = Float

type alias Y = Float

createAlt : X -> Y -> Vector2
createAlt = Vector2

Each approach has its downsides but they are more clear than the initial attempt.

4 Likes
5

Thanks for the follow up thoughts!

You were close, but I was thinking of Dict.merge (core/Dict.elm at 84f38891468e8e153fc85a9b63bdafd81b24664e · elm/core · GitHub)

6

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.