I would like to improve the API documentation

[marick]

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.

[michaelficarra]

Maybe it would be enough if the documentation generator had a way to mark some exports as "priority" for documentation purposes?

[hdgarrood]

The order that exported declarations appear in the docs is the same as that of the export list, so there's no need to reorganise the order they appear in the source. I agree that the current ordering is not optimal, so I would be in favour of a pull request along these lines. I'm not keen on adding features to the docs generator to mark exports as 'priority', personally. I would however like to enable authors to provide more structure in the generated docs eventually (see purescript/purescript#2525).

…

On Sat, 7 Apr 2018, at 03:45, Michael Ficarra wrote: Maybe it would be enough if the documentation generator had a way to mark some exports as "priority" for documentation purposes? -- You are receiving this because you are subscribed to this thread. Reply to this email directly or view it on GitHub: #142 (comment)

[marick]

Will do some rearranging.

[marick]

I've confirmed that moving

-- | Render a `Map` as a `String`
showTree :: forall k v. Show k => Show v => Map k v -> String
...

... 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]

Are you using an old compiler?

[marick]

I see I was not. (0.11.6 instead of 0.11.7) .

(Why does npm -g update not update purs, given that no argument is supposed to update everything? I had to give npm -g update purescript.

In any case, that fixes the ordering.

[marick]

(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.)

module Data.Map
  ( Map
  -- creation  
  , empty
  , singleton
  , fromFoldable
  , fromFoldableWith

  -- common ops
  , lookup
  , insert
  , delete

  -- queries
  , member
  , size
  , isEmpty

  -- manipulation of keys and values
  , keys
  , values
  , mapWithKey

  -- less common
  , update
  , alter
  , pop
    
  -- setlike
  , union
  , unionWith
  , unions
  , isSubmap

  -- filters
  , filter
  , filterWithKey
  , filterKeys

  -- taking advantage of Ord
  , lookupLE
  , lookupLT
  , lookupGE
  , lookupGT
  , findMin
  , findMax
  , submap
  , foldSubmap

  -- Unfoldable
  , toUnfoldable
  , toAscUnfoldable

  -- utils
  , showTree
  , checkValid
  ) where

[hdgarrood]

That looks good to me, yep!