Adds Identity API to docs #38

rstegg · 2017-01-26T18:27:12Z

This is a PR for issue #42.

A WIP API for crocks; you should review it and change what you'd like, and add to readme; it's modeled after the most.js api

Not much to dispute here; mostly copied from readme 🧀

evilsoft · 2017-01-27T23:41:31Z

This is an amazing start!
Thanks so much. Would you mind adding this folder to the .npmignore so we do not push documentation to the package.

I am a little worried about this getting stale and an extra thing to remember to do. It could get out of date easily. So we may want to update the main readme to lose the hard coupling.

But that is something we can fix up.

evilsoft · 2017-01-27T23:43:42Z

Don't worry about updating the README, we can adjust that after the docs get a bit more fleshed out.

evilsoft · 2017-01-28T08:10:47Z

docs/API.md

+
+## Monoids
+
+Each `Monoid` provides a means to represent a binary operation and is usually locked down to a specific type. These are great when you need to combine a list of values down to one value. In this library, any ADT that provides both an `empty` and `concat` function can be used as a `Monoid`. There are a few of the `Crocks` that are also monoidial, so be on the look out for those as well. All `Monoids` work with the point-free functions `mconcat`, `mreduce`, `mconcatMap` and `mreduceMap`.


Why get rid of the crocks description and leave this one?

Actually the more I think about it, we should probably keep all descriptions here.
So instead of removing the descriptions, we should probably add the crocks description back.

evilsoft · 2017-01-28T08:11:30Z

docs/API.md

+
+## Point-free
+
+While it can seem natural to work with all these containers in a fluent fashion, it can get cumbersome and hard to get a lot of reuse out of. A way to really get the most out of reusability in Javascript is to take what is called a point-free approach. Below is a small code same to contrast the difference between the two calling styles:


Also may want to get rid of this one as well?

Keep this and add back the crocks description.

I was not sure whether to add them here or keep them in the README, so they were purposely inconsistent for option; does your new issue #42 makes these suggestions obsolete, or what do you think?

I would add the crocks section. We can take it out if we need to once we cut over to these docs.

Add docs to npmignore

rstegg

Pointing out differences in the types of definitions. The ideas are there but the examples [looking at you, Constructor of] might suck

rstegg · 2017-01-29T01:42:57Z

docs/crocks/Identity.md

+### chain
+
+`(a -> m b) -> m b`
+


Different types of instance definitions: explicit Function vs implicit f, and implicit m vs (not sure what m stands for)

Here m is used to represent any Monad:
Monad m => (a -> m b) -> m b.

So as this is specifically an Identity, it could (and maybe should) be written as:
(a -> Identity b) -> Identity b

Although it would probably look better as:
Identity m => (a -> m b) -> m b

If that makes sense?

But then should all defs be prefixed by the representing monad?

rstegg · 2017-01-29T01:47:27Z

docs/crocks/Identity.md

+crocks.Identity.of([1,2,10])
+crocks.Identity([1,2,10])
+```
+


Different type of definition for constructor; here is only a definition by example

of is a very specific function that signals an Applicative.
In many cases the normal constructor function is the same thing as of.
We still include of in those cases so any functions that rely on calling of can call it.

So the constructor parameters should be represented by the type siggy in most cases.
For things like Writer it takes a Monoid and kicks you back a constructor that is fixed to that Monoid like: Writer (Sum b) a

Also for Maybe, it also takes an internal UnionType and if it is not the UnionType, it delegates to Maybe.of (which is basically Maybe.Just)

Good 👁 tho.

Actually a better example to highlight the difference would be IO.
You can only construct an IO with a function. BUT of will take anything you pass it and not check it at all and give you back an IO, that when run, returns whatever it was you passed of

evilsoft · 2017-01-29T03:22:35Z

@rstegg This is really shaping up nicely.
Thanks so much for jumping into this so enthusiastically. Excited to see what you do with all of this.

coveralls · 2017-02-06T20:53:08Z

Coverage remained the same at 100.0% when pulling 077e492 on rstegg:navigation-api into 5745f6b on evilsoft:docs.

coveralls · 2017-02-06T21:33:13Z

Coverage remained the same at 100.0% when pulling 177289e on rstegg:navigation-api into 5745f6b on evilsoft:docs.

coveralls · 2017-02-06T21:33:13Z

Coverage remained the same at 100.0% when pulling 177289e on rstegg:navigation-api into 5745f6b on evilsoft:docs.

coveralls · 2017-02-06T21:36:35Z

Coverage remained the same at 100.0% when pulling ebc65ea on rstegg:navigation-api into 5745f6b on evilsoft:docs.

coveralls · 2017-02-06T21:55:17Z

Coverage remained the same at 100.0% when pulling 1d0c505 on rstegg:navigation-api into 5745f6b on evilsoft:docs.

coveralls · 2017-02-06T22:05:08Z

Coverage remained the same at 100.0% when pulling bed1526 on rstegg:navigation-api into 5745f6b on evilsoft:docs.

rstegg · 2017-02-06T20:59:25Z

docs/crocks/Identity.md

-const dinner = frozenPizza.map(microwave) //Identity "microwave pizza"
-dinner.value() // "microwave pizza"
-```
+To expose the constructor and instances defined below


To expose the constructor and instances defined below to the argument ?

rstegg · 2017-02-06T21:01:00Z

docs/crocks/Identity.md


 ### equals

-`x -> Boolean`
+`Identity x => x -> Boolean`


❓ : does this really need to be defined here or should a top-level api define this?

coveralls · 2017-02-06T22:32:33Z

Coverage remained the same at 100.0% when pulling 121433d on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-07T02:12:17Z

Coverage remained the same at 100.0% when pulling fa420c7 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

evilsoft

Please check out my comments, and please ask any questions if you have them!!

evilsoft · 2017-02-07T03:15:22Z

docs/crocks/Identity.md

+
+### of
+
+`Identity a => a -> Identity a`


Should be something like:
Identity m => a -> m a

evilsoft · 2017-02-07T03:16:41Z

docs/crocks/Identity.md

+
+## Instances
+
+### inspect


inspect should be along the lines of:
() -> String

Identity () -> ?

No need to call out Identity here. this function just maps unit to a string.

evilsoft · 2017-02-07T03:18:28Z

docs/crocks/Identity.md

+
+### value
+
+`() -> a`


value should show be all like:

`Identity m => m a ~> () => a

I do not understand this one, folding Identity m => m a -> a?

value just maps unit to whatever is inside the identity.

// `a` would be Number in this case Identity(3) .value() // returns 3

evilsoft · 2017-02-07T03:19:15Z

docs/crocks/Identity.md

+
+### type
+
+`() -> Identity`


type returns a string identifier so something like:
() -> String

evilsoft · 2017-02-07T03:21:33Z

docs/crocks/Identity.md

+
+### map
+
+`Identity m => m (a -> b) -> m b`


So map takes a function and lifts it into the context of Identity, and because we need to show how the mapping works, we will want to use ~> here. So this is how it should be shown IMO:
Identity m => m a ~> (a -> b) -> m b

evilsoft · 2017-02-07T03:23:33Z

docs/crocks/Identity.md

+
+### ap
+
+`Identity m => m a ~> m (a -> b) -> m b`


This siggy matches the Fantasy Land spec and it just so happens this is the only place in crocks that does not match the spec (for reasons). So to get it to show how crocks handles Apply, it should be something like:
Identity m => m (a -> b) ~> m a -> m b.

Notice how it is reversed.

why do i feel like half of this can be thrown away?

Identity m => m (a -> b) or Identity m => m a -> m b? (just factoring the m, not actually defining a signature, is it?)

I don't know what you feel that.

There is a constraint that the instance that this is being called on, MUST contain a function.
So that is why m (a -> b) is needed to the left of ~>...We need to communicate that constraint.

Make sense? Do you have any ideas on how we could better communicate that constraint?
👂

Identity m => m a -> (a -> b) ~> m a -> m b

well i feel silly for trying now

evilsoft · 2017-02-07T03:26:35Z

docs/crocks/Identity.md

+
+### of
+
+`Identity a => a -> Identity a`


Should stick with the "shorthand" for 🌽sistancy. Even though this is on the instance for 🌽venience, we do not really need to show the instance, as this function is not dependent on the instance (?)

Identity m => a -> m a

evilsoft · 2017-02-07T03:27:00Z

docs/crocks/Identity.md

+
+### chain
+
+`Identity m => m a ~> (a -> m b) -> m b`


🐱fect!! This is exactly right!!

evilsoft · 2017-02-07T03:31:28Z

docs/crocks/Identity.md

+
+### sequence
+
+`Identity m, Applicative f => m (f b) ~> f (m a) -> m (f a)`


So for sequence we need an f returning function as the argument, but it is independent of the other types in this flow. so we can show that by using b like this:
Identity m, Applicative f => m (f a) ~> (b -> f b) -> f (m a)

Curious if m a ~> (b -> f b) -> f (m a) works for 🌽 sistency to traverse then?

nope. we need to already contain the f a for sequence.

In fact, that is the thing about sequence, it must already contain the Applicative.
Where traverse has a value and takes a function that will lift that value (and apply any additional mapping to it, if it wants) into the Applicative, and then sequence over that.

Does that make sense?

Good 👁 though! in catching the similarity

evilsoft · 2017-02-07T03:36:14Z

docs/crocks/Identity.md

+
+### traverse
+
+`Identity m, Applicative f => m a ~> f (m b) -> m (f b)`


And this bad boy should be something along the lines of
Identity m, Applicative f => m a ~> (c -> f c) -> (a -> f b) -> f (m b)

(The siggy is wrong for the crocks pointfree function. I will update that with the next PR. It should take a m a and not a m (f a) like it says. 🙄 )

coveralls · 2017-02-07T08:48:17Z

Coverage remained the same at 100.0% when pulling b2775be on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-07T08:48:17Z

Coverage remained the same at 100.0% when pulling b2775be on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-07T08:48:17Z

Coverage remained the same at 100.0% when pulling b2775be on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-07T22:27:01Z

Coverage remained the same at 100.0% when pulling 82df8f7 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-07T22:51:28Z

Coverage remained the same at 100.0% when pulling 3020043 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-08T19:41:01Z

Coverage remained the same at 100.0% when pulling 8389a03 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-08T19:41:01Z

Coverage remained the same at 100.0% when pulling 8389a03 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-08T19:41:02Z

Coverage remained the same at 100.0% when pulling 8389a03 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

rstegg · 2017-02-08T19:42:14Z

On Either, only worked on the sigs, nothing above it. next commit after review will have those changes

coveralls · 2017-02-08T21:59:51Z

Coverage remained the same at 100.0% when pulling 3736fbb on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

coveralls · 2017-02-08T22:09:01Z

Coverage remained the same at 100.0% when pulling 32be547 on rstegg:navigation-api into 7a4ba53 on evilsoft:docs.

evilsoft · 2017-02-10T02:31:57Z

Merging...Here is a squirrel

* Add API documentation

Add API documentation

95d13a7

evilsoft reviewed Jan 28, 2017

View reviewed changes

Add experimental identity api

facce30

Add docs to npmignore

rstegg commented Jan 29, 2017

View reviewed changes

rstegg changed the base branch from master to docs February 6, 2017 20:22

Update Identity.md api

077e492

rstegg commented Feb 6, 2017

View reviewed changes

Removes API readme, updates Identity.md sigs

fa420c7

evilsoft reviewed Feb 7, 2017

View reviewed changes

Fixes identity sigs, again. adds more flair to the subheader

b2775be

Add experimental Dictionary api

82df8f7

Update usage with Identity

3020043

Add 💄 to Identity api

3736fbb

Fix-up: Identity code examples moved into one block

32be547

rstegg changed the title ~~Add docs/API.md documentation, no changes to Readme~~ Add Identity API to docs Feb 10, 2017

rstegg changed the title ~~Add Identity API to docs~~ Adds Identity API to docs Feb 10, 2017

evilsoft merged commit 6674ae9 into evilsoft:docs Feb 10, 2017

evilsoft pushed a commit that referenced this pull request Mar 1, 2017

Adds Identity API to docs (#38)

c22b2b5

* Add API documentation

evilsoft pushed a commit that referenced this pull request Mar 13, 2017

Adds Identity API to docs (#38)

c32b41f

* Add API documentation


		## Monoids

		Each `Monoid` provides a means to represent a binary operation and is usually locked down to a specific type. These are great when you need to combine a list of values down to one value. In this library, any ADT that provides both an `empty` and `concat` function can be used as a `Monoid`. There are a few of the `Crocks` that are also monoidial, so be on the look out for those as well. All `Monoids` work with the point-free functions `mconcat`, `mreduce`, `mconcatMap` and `mreduceMap`.


		## Point-free

		While it can seem natural to work with all these containers in a fluent fashion, it can get cumbersome and hard to get a lot of reuse out of. A way to really get the most out of reusability in Javascript is to take what is called a point-free approach. Below is a small code same to contrast the difference between the two calling styles:


		### sequence

		`Identity m, Applicative f => m (f b) ~> f (m a) -> m (f a)`


		### traverse

		`Identity m, Applicative f => m a ~> f (m b) -> m (f b)`

Adds Identity API to docs #38

Adds Identity API to docs #38

Conversation

rstegg commented Jan 26, 2017 • edited Loading

evilsoft commented Jan 27, 2017

evilsoft commented Jan 27, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rstegg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evilsoft Jan 29, 2017 • edited Loading

Choose a reason for hiding this comment

evilsoft commented Jan 29, 2017

coveralls commented Feb 6, 2017 • edited Loading

coveralls commented Feb 6, 2017

coveralls commented Feb 6, 2017 • edited Loading

coveralls commented Feb 6, 2017 • edited Loading

coveralls commented Feb 6, 2017 • edited Loading

coveralls commented Feb 6, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Feb 6, 2017 • edited Loading

coveralls commented Feb 7, 2017 • edited Loading

evilsoft left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rstegg Feb 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rstegg Feb 7, 2017 • edited Loading

Choose a reason for hiding this comment

rstegg Feb 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coveralls commented Feb 7, 2017

coveralls commented Feb 7, 2017 • edited Loading

coveralls commented Feb 7, 2017

coveralls commented Feb 7, 2017 • edited Loading

coveralls commented Feb 7, 2017 • edited Loading

coveralls commented Feb 8, 2017

coveralls commented Feb 8, 2017

coveralls commented Feb 8, 2017 • edited Loading

rstegg commented Feb 8, 2017

coveralls commented Feb 8, 2017 • edited Loading

coveralls commented Feb 8, 2017 • edited Loading

evilsoft commented Feb 10, 2017

rstegg commented Jan 26, 2017 •

edited

Loading

evilsoft Jan 29, 2017 •

edited

Loading

coveralls commented Feb 6, 2017 •

edited

Loading

coveralls commented Feb 6, 2017 •

edited

Loading

coveralls commented Feb 6, 2017 •

edited

Loading

coveralls commented Feb 6, 2017 •

edited

Loading

coveralls commented Feb 6, 2017 •

edited

Loading

coveralls commented Feb 6, 2017 •

edited

Loading

coveralls commented Feb 7, 2017 •

edited

Loading

rstegg Feb 7, 2017 •

edited

Loading

rstegg Feb 7, 2017 •

edited

Loading

rstegg Feb 7, 2017 •

edited

Loading

coveralls commented Feb 7, 2017 •

edited

Loading

coveralls commented Feb 7, 2017 •

edited

Loading

coveralls commented Feb 7, 2017 •

edited

Loading

coveralls commented Feb 8, 2017 •

edited

Loading

coveralls commented Feb 8, 2017 •

edited

Loading

coveralls commented Feb 8, 2017 •

edited

Loading