dateFromFields and timeFromFields documentation could be improved

[akrejczinger]

The documentation only contains the signature of the function, but no usage example or explanation of each parameter.

dateFromFields
    :  Int
    -> Month
    -> Int
    -> Int
    -> Int
    -> Int
    -> Int
    -> Date

timeFromFields : Int -> Int -> Int -> Int -> Date

What are all those Ints? What does each mean? Based on this documentation a user might try to create a date in the US format like this: dateFromFields 02 Feb 2018 13 52 0 0 0 I also cannot tell what the last two numbers are without looking at the source. The same applies to timeFromFields.

[rluiten]

Ahh yes, one of my pet peeves with the documentation output, it discards the actual names of the parameters, though to be fair with currying as in the timeFromFields case there are no explicit parameter names, but an inspired tool could grab them from upstream names maybe.

I have added a call signature to each one for now published in 9.3.1.

[rluiten]

If I add aliases like the following one for Year and use them.

type alias Year =
    Int

dateFromFields : Year -> Month -> Day -> Hour -> Minute -> Second -> Millisecond -> Date

The consequence is a major version bump due to the interface changing. I have to think about this some more and look at applying it globally if I am going to do this.

Have attached documenation.json.txt which can be loaded into http://package.elm-lang.org/help/docs-preview if you want a look at how the documentation looks using these aliases in Create module.

documentation.json.txt

[rluiten]

Just had a suggestion that maybe a record format dateFromFields with named record fields is another option.

[akrejczinger]

The record format actually sounds like the best option. Pro: the calling function will also be self-documenting. Example: instead of the current call format

dateFromFields 1990 Feb 1 2 3 4 5

we would have something a lot more readable:

dateFromFields
  { year = 1990
  , mont = Feb
  , day = 1
  , hour = 2
  , minute = 3
  , second = 4
  , millisecond = 5
  }

Contra: we lose currying, but it's not very useful in this case anyways.

Thank you for considering my suggestions. I'm pretty new to elm and working with dates tripped me up a bit.