Repository navigation
I would like to improve the API documentation #142
Description
I come from Elm. I find its API documentation helpful because the more common functions are at the beginning.
I'm not criticizing! I want to help!
Here's the first 5 documented functions from Dict:
Build (major category)
- empty
- singleton
- update
- insert
- remove
Here are the first 5 from Data.Map:
- showTree
- empty
- isEmpty
- singleton
- checkValue
I think the Elm API documentation is better. checkValue is not important. When i want to look for a function, I find it faster in the Elm documentation.
Elm has the advantage that their doc format lets you categorize. Still, I think Data.Map API documentation could be improved with better organization. People who haven't memorized the key parts of the API want to know whether the "add a new element" function is add or insert without having to scroll past lookupLt, lookupGE, lookupGT, findSubMap, and subMap.
I volunteer to reorganize the functions in the source to put the more common ones first, if someone says they'd accept such a pull request.
Activity
michaelficarra commentedon Apr 7, 2018
Maybe it would be enough if the documentation generator had a way to mark some exports as "priority" for documentation purposes?
hdgarrood commentedon Apr 7, 2018
marick commentedon Apr 7, 2018
Will do some rearranging.
marick commentedon Apr 7, 2018
I've confirmed that moving
... to the end of the file does in fact put at the end of the generated-doc list.
But rearranging the file to match the order given above is pretty problematic given 11 pull requests.
hdgarrood commentedon Apr 8, 2018
Are you using an old compiler?
marick commentedon Apr 8, 2018
I see I was not. (0.11.6 instead of 0.11.7) .
(Why does
npm -g updatenot update purs, given that no argument is supposed to update everything? I had to givenpm -g update purescript.In any case, that fixes the ordering.
marick commentedon Apr 8, 2018
(And what happened to the comment where I reported the problem? It had the version numbers, but more importantly, I was hoping for a thumbs-up on the proposed order before fashioning a pull request.)
hdgarrood commentedon Apr 10, 2018
That looks good to me, yep!