my biggest issue with the vast majority of PL APIs is discoverability. for the most part, they work best if you literally skim every class/type/function/method/module you can and just... know them.
then there's Hoogle, which says "dream of a type and I shall provide a function."
Conversation
hands-down, Hoogle is the most impressive documentation resource I've ever found. I look at the types of data I've found myself with, mash in some arrows, and Hoogle says "someone implemented a library that does exactly what you want". it's glorious. every PL needs a Hoogle.
2
11
these thoughts brought to you by "I have a Vec and I'm sure there's a way to delete all its contents. delete_all? no, doesn't exist. drop? ah, that's a destructor. uhhh empty? destroy? clear? oh, it's clear! nice."
2
1
(admittedly I do not know by what type signature I could ever find this function, unless side-effects were encoded efficiently in the types. but it made me think about how much I love using Hoogle to find functions/operators when writing Haskell.)
1
1
IMO there's a ton of low hanging fruit in UI design for auto-generated docs. Here's a mockup I did for Rustdoc to address this exact issue:
3
3
I do like where this is headed, but it seems like it still requires me to just kinda skim it for maximum helpfulness, right? what's magical to me about Hoogle is I get to skip that step. I create a specification and am told what already meets my needs.
1
Right, this interface still requires visual search. I find most documentation searches can't be easily expressed as a type-based query, but then again I don't use Haskell!
1
1
ah I feel like you're right that many won't work that way. maybe Haskell benefits from being more "about types" than most languages so it works out better. no other PL tool has given me the same satisfaction though. it's unparalleled (in that type-oriented context).
1
2
I'd imagine you could get a similar experience for Koka for example! Effects being explicit makes this kind of search much easier.
I've yet to give Koka a shot — maybe I should make time for that at some point!