Add `arrow.generic.Coproduct` docs #998

abergfeld · 2018-08-24T17:30:22Z

This adds docs for Coproducts. I largely based this off the Products docs that already existed. I'm not sure if I have to add anything else to get these setup with the web pages or how all that works. These are my first Arrow docs so feedback would be much appreciated :)

JorgeCastilloPrz · 2018-08-24T17:33:26Z

If you wanna test the docs locally:

Run Ank, it'll deploy docs locally for you.
./gradlew :arrow-docs:runAnk in the root Arrow folder.

Once that's finished, go to modules/docs/arrow-docs/ and then

jekyll serve --source build/site/

That will launch the site on 127.0.0.1:4000. You'll need Jekyll installed.

abergfeld · 2018-08-24T19:58:11Z

@JorgeCastilloPrz Thanks! I got the readme code compiling and hooked up the menu and it's all working locally 🎉

codecov · 2018-08-27T15:17:46Z

Codecov Report

Merging #998 into master will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##             master     #998   +/-   ##
=========================================
  Coverage     47.04%   47.04%           
  Complexity      694      694           
=========================================
  Files           320      320           
  Lines          8090     8090           
  Branches        848      848           
=========================================
  Hits           3806     3806           
  Misses         3941     3941           
  Partials        343      343

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ab442f2...ed00f01. Read the comment docs.

JorgeCastilloPrz · 2018-08-27T18:31:15Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+
+Coproducts represent a container in which only one of the specified set of types exist. It's very similar in `Either` in that respect. `Either` supports one of two values, an `Either<A, B>` has to contain an instance of `A` or `B`. We can extrapolate that concept to `N` number of types. So a `Coproduct5<A, B, C, D, E>` has to contain an instance of `A`, `B`, `C`, `D`, or `E`. For example, perhaps there's a search function for a Car Dealer app that can show `Dealership`s, `Car`s and `SalesPerson`s, we could model that list of results as `List<Coproduct3<Dealership, Car, SalesPerson>`. The result would contain a list of heterogeneous elements but each element is one of `Dealership`, `Car` or `SalesPerson` and our UI can render the list elements based on those types.
+
+Let's say we have an api. Our api operates under the following conditions:


All this scenarios would work better using very simple code snippets.

JorgeCastilloPrz · 2018-08-27T18:32:03Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+
+#### Coproduct
+
+Coproducts represent a container in which only one of the specified set of types exist. It's very similar in `Either` in that respect. `Either` supports one of two values, an `Either<A, B>` has to contain an instance of `A` or `B`. We can extrapolate that concept to `N` number of types. So a `Coproduct5<A, B, C, D, E>` has to contain an instance of `A`, `B`, `C`, `D`, or `E`. For example, perhaps there's a search function for a Car Dealer app that can show `Dealership`s, `Car`s and `SalesPerson`s, we could model that list of results as `List<Coproduct3<Dealership, Car, SalesPerson>`. The result would contain a list of heterogeneous elements but each element is one of `Dealership`, `Car` or `SalesPerson` and our UI can render the list elements based on those types.


Please add links to Either docs everytime you mention it.

JorgeCastilloPrz · 2018-08-27T18:34:04Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+val apiResult = coproductOf<CommonServerError, RegistrationError, Registration>(ServerError) //Returns Coproduct3<CommonServerError, RegistrationError, Registration>
+```
+
+There are `coproductOf` constructor functions for each Coproduct. All we have to do is pass in our value and have the correct type parameters on it, the value must be a type declared on the function call.


First line, I'd better say "...for each Coproduct regardless of the arity (number of types)."

JorgeCastilloPrz · 2018-08-28T08:49:16Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+{:.beginner}
+beginner
+
+`arrow-generic` provides meta programming facilities over Product types like data classes, tuples, and heterogeneous lists; and Coproduct types like sealed classes.


What about "arrow-generic provides meta programming facilities over Product types (data classes, tuples, heterogeneous lists...). It also provides the Coproduct type, similar to sealed classes.

(Even if by implementation we're providing N Coproduct types, semantically all of them are the same thing, the Coproduct, I don't think there's need here to state it's a bunch of them, at least not yet on this paragraph)

JorgeCastilloPrz · 2018-08-28T08:51:19Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+
+#### Coproduct
+
+Coproducts represent a container in which only one of the specified set of types exist. It's very similar in `Either` in that respect. `Either` supports one of two values, an `Either<A, B>` has to contain an instance of `A` or `B`. We can extrapolate that concept to `N` number of types. So a `Coproduct5<A, B, C, D, E>` has to contain an instance of `A`, `B`, `C`, `D`, or `E`. For example, perhaps there's a search function for a Car Dealer app that can show `Dealership`s, `Car`s and `SalesPerson`s, we could model that list of results as `List<Coproduct3<Dealership, Car, SalesPerson>`. The result would contain a list of heterogeneous elements but each element is one of `Dealership`, `Car` or `SalesPerson` and our UI can render the list elements based on those types.


"Coproducts represent a sealed hierarchy of types where only one of the specified set of types exist every time. Conceptually, it's very similar to the stdlib sealed class, or to Either if we move on to Arrow data types."

"...Car Dealer app that can show Dealerships, Cars and SalesPersons on a list.."

JorgeCastilloPrz · 2018-08-28T08:54:18Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+All we have to do is provide the type parameters and we can make a Coproduct using the `cop` extension method. Just like `coproductOf`, if the type of the value isn't in the type parameters of the method call, it won't compile:
+
+```kotlin:ank
+//val apiResult = ServerError.cop<String, RegistrationError, Registration>()


Can we write the exception thrown here?

JorgeCastilloPrz · 2018-08-28T08:55:22Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+
+##### fold
+
+Obviously, we're not just modeling errors for fun, we're going to handle them! All Coproducts have `fold` which allows us to condense the Coproduct down to a single type. For example, we could handle errors as such in a UI:


Maybe we can add some note here about exhaustive evaluation?

JorgeCastilloPrz · 2018-08-28T08:56:46Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+    )
+```
+
+Here we're able to return the result of the `fold` and we're forced to handle all cases! Neat!


Ah! There it is. Maybe just explicitly mention exhaustive evaluation here. You're saying it but still mentioning it by its real name should help.

JorgeCastilloPrz · 2018-08-28T08:58:14Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+
+##### select
+
+Let's say we also want to store the `Registration` object into our database when we successfully register a car. We don't really want to have to `fold` over every single case just to handle something for the `Registration`, this is where `select<T>` comes to the rescue! We're able to take a Coproduct and `select` the type we care about from it. `select` returns an `Option`, if the value of the Coproduct was for the type you're trying to `select`, you'll get `Some`, if it was not the type used with `select`, you'll get `None`.


Maybe we could move all the first part until "...select comes to the rescue!" to the previous section. Then you present select as a new section, which would start as "We're able to take a...". That helps to start introducing the concept by the need for it before even giving it a name. It's just a more gradual way to put it.

abergfeld · 2018-08-29T00:56:19Z

@JorgeCastilloPrz I updated the docs, I think I addressed everything. Let me know if there's anything else :)

abergfeld · 2018-08-29T14:05:24Z

@ffgiraldez Would you be able to help me figure out what's happening with the code coverage testing here, it all looks like stuff that hasn't changed as part of this PR.

raulraja · 2018-08-29T14:58:09Z

modules/docs/arrow-docs/docs/docs/generic/coproduct/README.md

+
+fun handleApiResult(apiResult: Coproduct3<CommonServerError, RegistrationError, Registration>): Unit {
+//    apiResult.select<String>()
+//error: type mismatch: inferred type is Coproduct3<CommonServerError, RegistrationError, Registration> but Coproduct3<String, *, *> was expected


This reminds me that Ank should have a mode for expecting and printing errors similar to how we do now ank:silent. but ank:error so users are not forced to comment out code that fails to compile and can let the compiler provide the actual error that gets rendered along the snippet.

/cc @Guardiola31337

ffgiraldez · 2018-08-29T22:03:53Z

I will check It tomorrow

raulraja · 2018-09-01T15:28:52Z

thanks @abergfeld !

abergfeld added 2 commits August 24, 2018 12:18

Add docs around Coproduct

d371e35

Clean up phrasing / type casing

2e42863

abergfeld added 2 commits August 24, 2018 14:45

It's compiling docs

cf53d9c

Add Coproducts under the generic menu

c9b4067

Remove unused imports

652cf61

JorgeCastilloPrz approved these changes Aug 27, 2018

View reviewed changes

JorgeCastilloPrz reviewed Aug 28, 2018

View reviewed changes

abergfeld added 4 commits August 28, 2018 19:37

Update after comments

1b7c749

Add errors to non compiling snippets

7384f3c

Fix snippet

9e40b5b

Merge branch 'master' into ab-add-coproduct-docs

e70b421

raulraja reviewed Aug 29, 2018

View reviewed changes

JorgeCastilloPrz mentioned this pull request Aug 29, 2018

updating blogs and presentation docs #1001

Merged

Merge branch 'master' into ab-add-coproduct-docs

ed00f01

raulraja merged commit b5ec6e4 into arrow-kt:master Sep 1, 2018

calvellido added docs and removed docs labels Oct 17, 2018

raulraja mentioned this pull request Nov 2, 2018

Release 0.8.0 #1080

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add `arrow.generic.Coproduct` docs #998

Add `arrow.generic.Coproduct` docs #998

abergfeld commented Aug 24, 2018

JorgeCastilloPrz commented Aug 24, 2018

abergfeld commented Aug 24, 2018

codecov bot commented Aug 27, 2018 •

edited

Loading

JorgeCastilloPrz Aug 27, 2018

JorgeCastilloPrz Aug 27, 2018

JorgeCastilloPrz Aug 27, 2018

JorgeCastilloPrz Aug 28, 2018

JorgeCastilloPrz Aug 28, 2018 •

edited

Loading

JorgeCastilloPrz Aug 28, 2018

JorgeCastilloPrz Aug 28, 2018

JorgeCastilloPrz Aug 28, 2018 •

edited

Loading

JorgeCastilloPrz Aug 28, 2018

JorgeCastilloPrz Aug 28, 2018 •

edited

Loading

abergfeld commented Aug 29, 2018

abergfeld commented Aug 29, 2018

raulraja Aug 29, 2018

raulraja Aug 29, 2018

ffgiraldez commented Aug 29, 2018

raulraja commented Sep 1, 2018


		Coproducts represent a container in which only one of the specified set of types exist. It's very similar in `Either` in that respect. `Either` supports one of two values, an `Either<A, B>` has to contain an instance of `A` or `B`. We can extrapolate that concept to `N` number of types. So a `Coproduct5<A, B, C, D, E>` has to contain an instance of `A`, `B`, `C`, `D`, or `E`. For example, perhaps there's a search function for a Car Dealer app that can show `Dealership`s, `Car`s and `SalesPerson`s, we could model that list of results as `List<Coproduct3<Dealership, Car, SalesPerson>`. The result would contain a list of heterogeneous elements but each element is one of `Dealership`, `Car` or `SalesPerson` and our UI can render the list elements based on those types.

		Let's say we have an api. Our api operates under the following conditions:


		#### Coproduct

		Coproducts represent a container in which only one of the specified set of types exist. It's very similar in `Either` in that respect. `Either` supports one of two values, an `Either<A, B>` has to contain an instance of `A` or `B`. We can extrapolate that concept to `N` number of types. So a `Coproduct5<A, B, C, D, E>` has to contain an instance of `A`, `B`, `C`, `D`, or `E`. For example, perhaps there's a search function for a Car Dealer app that can show `Dealership`s, `Car`s and `SalesPerson`s, we could model that list of results as `List<Coproduct3<Dealership, Car, SalesPerson>`. The result would contain a list of heterogeneous elements but each element is one of `Dealership`, `Car` or `SalesPerson` and our UI can render the list elements based on those types.


		##### fold

		Obviously, we're not just modeling errors for fun, we're going to handle them! All Coproducts have `fold` which allows us to condense the Coproduct down to a single type. For example, we could handle errors as such in a UI:


		##### select

		Let's say we also want to store the `Registration` object into our database when we successfully register a car. We don't really want to have to `fold` over every single case just to handle something for the `Registration`, this is where `select<T>` comes to the rescue! We're able to take a Coproduct and `select` the type we care about from it. `select` returns an `Option`, if the value of the Coproduct was for the type you're trying to `select`, you'll get `Some`, if it was not the type used with `select`, you'll get `None`.

Add arrow.generic.Coproduct docs #998

Add arrow.generic.Coproduct docs #998

Conversation

abergfeld commented Aug 24, 2018

JorgeCastilloPrz commented Aug 24, 2018

abergfeld commented Aug 24, 2018

codecov bot commented Aug 27, 2018 • edited Loading

Codecov Report

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

JorgeCastilloPrz Aug 28, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JorgeCastilloPrz Aug 28, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JorgeCastilloPrz Aug 28, 2018 • edited Loading

Choose a reason for hiding this comment

abergfeld commented Aug 29, 2018

abergfeld commented Aug 29, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ffgiraldez commented Aug 29, 2018

raulraja commented Sep 1, 2018

Add `arrow.generic.Coproduct` docs #998

Add `arrow.generic.Coproduct` docs #998

codecov bot commented Aug 27, 2018 •

edited

Loading

JorgeCastilloPrz Aug 28, 2018 •

edited

Loading

JorgeCastilloPrz Aug 28, 2018 •

edited

Loading

JorgeCastilloPrz Aug 28, 2018 •

edited

Loading