5 ms·

How often do you document an API in such a way? Does the frequency with which this occurs justify introducing new terminology? Plus, you artificially inflated t

How often do you document an API in such a way? Does the frequency with which this occurs justify introducing new terminology? Plus, you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is, while not even naming in your "short" case what the operation and neutral element are.

tome 9y ago
> How often do you document an API in such a way? Every time `instance Monoid Foo` occurs in the Haddock documentation of a Haskell datatype which is pretty often! > Does the frequency with which this occurs justify introducing new terminology? "Justify" according to what set of criteria? Personally I prefer it. > you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is So your suggestion is * baz is associative and quux is a neutral element for it Really, if you're going to go that far you may as well go all the way and just say * Foo is a Monoid under baz and quux > while not even naming in your "short" case what the operation and neutral element are. Well, in the Haskell world they're implied by the typeclass instance, but I take your point.
marcosdumay 9y ago
If you are writing Haskell, you document your code this way first¹, and what is missing from this kind of definition you write down with words. It's incredibly useful, since you can just go into Hoogle or some similar tool and query a function that: Monoid m => (a -> m) -> [a] -> m And it will tell you it's called `foldMap`, and is available by default. Not long ago I have made this exact query because I forgot the name. 1 - Well, the autodoc write those comments for you.
romwell 9y ago
I think at this point, I'll settle on "code people like taking fancy words from math people and running with them". Associativity is a boring word, because high-schoolers have seen it. Eh. Your patience here is admirable.

tome 9y ago

> How often do you document an API in such a way? Every time `instance Monoid Foo` occurs in the Haddock documentation of a Haskell datatype which is pretty often! > Does the frequency with which this occurs justify introducing new terminology? "Justify" according to what set of criteria? Personally I prefer it. > you artificially inflated the wording to make "x is associative and has a neutral element y" look more complicated than it actually is So your suggestion is * baz is associative and quux is a neutral element for it Really, if you're going to go that far you may as well go all the way and just say * Foo is a Monoid under baz and quux > while not even naming in your "short" case what the operation and neutral element are. Well, in the Haskell world they're implied by the typeclass instance, but I take your point.

marcosdumay 9y ago

If you are writing Haskell, you document your code this way first¹, and what is missing from this kind of definition you write down with words. It's incredibly useful, since you can just go into Hoogle or some similar tool and query a function that: Monoid m => (a -> m) -> [a] -> m And it will tell you it's called `foldMap`, and is available by default. Not long ago I have made this exact query because I forgot the name. 1 - Well, the autodoc write those comments for you.

romwell 9y ago

I think at this point, I'll settle on "code people like taking fancy words from math people and running with them". Associativity is a boring word, because high-schoolers have seen it. Eh. Your patience here is admirable.