First approach to `NonEmptyList` docs #1971

AlejandroME · 2017-10-15T21:23:08Z

This is the first draft for NonEmptyList docs, as required by #1801.

I'm requesting feedback about this. What should we have to explore in this docs? I've seen the API of NonEmptyList and I find a lot of similarities with plain old List that I don't find useful to address here.

I appreciate your comments about this WIP and suggestions about what should we put in here.

Thanks!

codecov-io · 2017-10-15T22:03:12Z

Codecov Report

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

@@           Coverage Diff           @@
##           master    #1971   +/-   ##
=======================================
  Coverage   95.08%   95.08%           
=======================================
  Files         301      301           
  Lines        4943     4943           
  Branches      125      124    -1     
=======================================
  Hits         4700     4700           
  Misses        243      243

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 77ac6bf...2b483c7. Read the comment docs.

AlejandroME · 2017-10-27T15:22:36Z

@kailuowang and @LukaJCB: can you give me some advice on this? :)

LukaJCB · 2017-10-27T15:23:53Z

Hey @AlejandroME Sorry, for not getting back to you earlier, I'm going to give you a review later today :)

rossabaker

Thanks! I think this is a solid start.

rossabaker · 2017-10-27T15:25:42Z

docs/src/main/tut/datatypes/NonEmptyList.md

+---
+# NonEmptyList
+
+If you have had the opportunity of taking a look to [Validated](validated.html) or [IOR](ior.html), you'll find that one of the most common case is to use `NonEmptyList` with one of these data structures.


s/one of the most/a/

Thank you. I'll fix all the typos that you've found.

rossabaker · 2017-10-27T15:26:14Z

docs/src/main/tut/datatypes/NonEmptyList.md

+
+If you have had the opportunity of taking a look to [Validated](validated.html) or [IOR](ior.html), you'll find that one of the most common case is to use `NonEmptyList` with one of these data structures.
+
+Why? Because it fits nicely in the error reporting cases. As its stated by its name, `NonEmptyList` is a _specialized_ data type that will have, at least, one element. You'll find its behaviour like a list, with the aforementioned constraint. Think of it as a `List` wrapper.


s/As its stated/As stated/

rossabaker · 2017-10-27T15:27:49Z

docs/src/main/tut/datatypes/NonEmptyList.md

+}
+```
+
+The `head` of the will be _non empty_, meanwhile, the `tail` can have zero or more elements.


s/non empty, meanwhile/non-empty. Meanwhile/

rossabaker · 2017-10-27T15:30:35Z

docs/src/main/tut/datatypes/NonEmptyList.md

+list.head
+```
+
+You've seen the creation of a `NonEmptyList` with one `String` element (_"Hello"_), using `.of` combinator, but also you can create a `NonEmptyList` from a regular `List` like this:


I wouldn't call .of a combinator.

It would be nice to show that .of takes a variadic tail, too: NonEmptyList.of(1, 2, 3)

Perfect! I'll expand this section

rossabaker · 2017-10-27T15:30:46Z

docs/src/main/tut/datatypes/NonEmptyList.md

+val nel = NonEmptyList.fromList(regularList)
+```
+
+But, what happen if you try to convert an empty `List` into a `NonEmptyList`? Let's see:


s/happen/happens/

rossabaker · 2017-10-27T15:31:59Z

docs/src/main/tut/datatypes/NonEmptyList.md

+
+## All is about safety
+
+`List` has a lot of unsafe methods because it doesn't enforce any constraint (other than its type). If you do this:


Are we assuming that people know what "unsafe" means?

Good point! I could use an example for illustrating the concept.

rossabaker · 2017-10-27T15:35:06Z

docs/src/main/tut/datatypes/NonEmptyList.md

+
+You can see that you get a `NoSuchElementException` because you're trying to get the head of an empty `List`. The same behaviour applies with methods like `.last` or `.tail`.
+
+Using `NonEmptyList` you'll have the type safety in compile-time for this data type.


I think I might talk more about totality than type safety. Neither List[Orange].head nor NonEmptyList[Orange].head will ever give you an apple. It's just that the NEL will always give you an Orange.

Can you explain me in more depth? I don't understand you when you say "totality".

Total functions are functions that return a value for every input given. Partial functions (like List#head) don't have that guarantee and aren't defined for certain inputs.

Ah, ok, got it! So, based on @rossabaker feedback, should I rephrase this section to address totality instead of type safety or should I leave this as it is and expand it with totality?

I think totality instead of type safety.

- Fixed some typos. - Restructured Safety concept ("Safety" instead of "Type Safety"). - Explained briefly "Totality".

AlejandroME · 2017-11-06T17:48:27Z

This is the second iteration of the documentation based on @rossabaker and @LukaJCB feedback.
Apart from the suggested improvements, I don't know what else to address in these docs, so, if there's a lack of some concept important to detail here, please let me know.

Thanks! :)

…Docs

rethab · 2017-11-14T06:22:02Z

docs/src/main/tut/datatypes/NonEmptyList.md

+
+If you have had the opportunity of taking a look to [Validated](validated.html) or [IOR](ior.html), you'll find that a common case is to use `NonEmptyList` with one of these data structures.
+
+Why? Because it fits nicely in the error reporting cases. As stated by its name, `NonEmptyList` is a _specialized_ data type that will have, at least, one element. You'll find that its behavior is like a list, with the aforementioned constraint. Think of it as a `List` wrapper.


What does specialized mean here? When I first read this, I thought about @specialized but I guess it's not? I think this might be confusing.

Sorry, I mean that is a specific-purpose data type (compared to a regular List). I'll rephrase this.

rethab · 2017-11-14T06:27:01Z

docs/src/main/tut/datatypes/NonEmptyList.md

+```tut:book
+import cats.data.NonEmptyList
+
+val list = NonEmptyList.of("Hello")


Have you thought about adding types to your examples? I think this would demonstrate the difference between of and fromList more clearly:

val list: NonEmptyList[String] = NonEmptyList.of("Hello") val nel: Option[NonEmptyList[String]] = NonEmptyList.fromList(regularList)

Got it, I'll add it.

rethab · 2017-11-14T06:35:58Z

As you said in the intro of this PR, NonEmptyList supports many operations that a conventional List does. Perhaps add a comment about that.

Also, you could add an example about cats.syntax.list. I like groupByNel in particular, because for me, the regular groupBy was a typical case where I knew it would only produce non-empty lists, but the types did not express that.

More ideas:

reference/relate NonEmptyTraverse
reference/relate NonEmptyVector

AlejandroME · 2017-11-20T12:04:15Z

Thank you @rethab for your review. I'll work on your suggestions and refine a little bit this docs.

kailuowang · 2017-12-27T16:04:36Z

completed through #2107

First approach to NonEmptyList docs

54ac1d3

LukaJCB mentioned this pull request Oct 17, 2017

Documentation megathread #1801

Open

70 tasks

rossabaker reviewed Oct 27, 2017

View reviewed changes

Second iteration on NEL Docs

6f3c5bc

- Fixed some typos. - Restructured Safety concept ("Safety" instead of "Type Safety"). - Explained briefly "Totality".

Merge branch 'master' of https://github.com/AlejandroME/cats into nel…

2b483c7

…Docs

kailuowang added the documentation label Nov 13, 2017

rethab reviewed Nov 14, 2017

View reviewed changes

kailuowang mentioned this pull request Dec 14, 2017

Documentation for NonEmptyList #2107

Merged

kailuowang closed this Dec 27, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

First approach to `NonEmptyList` docs #1971

First approach to `NonEmptyList` docs #1971

AlejandroME commented Oct 15, 2017

codecov-io commented Oct 15, 2017 •

edited

Loading

AlejandroME commented Oct 27, 2017

LukaJCB commented Oct 27, 2017

rossabaker left a comment

rossabaker Oct 27, 2017

AlejandroME Oct 27, 2017

rossabaker Oct 27, 2017

rossabaker Oct 27, 2017

rossabaker Oct 27, 2017

AlejandroME Oct 27, 2017

rossabaker Oct 27, 2017

rossabaker Oct 27, 2017

AlejandroME Oct 27, 2017 •

edited

Loading

rossabaker Oct 27, 2017

AlejandroME Oct 27, 2017

LukaJCB Oct 27, 2017

AlejandroME Oct 27, 2017 •

edited

Loading

rossabaker Oct 28, 2017

AlejandroME commented Nov 6, 2017

rethab Nov 14, 2017

AlejandroME Nov 20, 2017

rethab Nov 14, 2017

AlejandroME Nov 20, 2017

rethab commented Nov 14, 2017

AlejandroME commented Nov 20, 2017

kailuowang commented Dec 27, 2017


		If you have had the opportunity of taking a look to [Validated](validated.html) or [IOR](ior.html), you'll find that one of the most common case is to use `NonEmptyList` with one of these data structures.

		Why? Because it fits nicely in the error reporting cases. As its stated by its name, `NonEmptyList` is a _specialized_ data type that will have, at least, one element. You'll find its behaviour like a list, with the aforementioned constraint. Think of it as a `List` wrapper.


		## All is about safety

		`List` has a lot of unsafe methods because it doesn't enforce any constraint (other than its type). If you do this:


		You can see that you get a `NoSuchElementException` because you're trying to get the head of an empty `List`. The same behaviour applies with methods like `.last` or `.tail`.

		Using `NonEmptyList` you'll have the type safety in compile-time for this data type.

First approach to NonEmptyList docs #1971

First approach to NonEmptyList docs #1971

Conversation

AlejandroME commented Oct 15, 2017

codecov-io commented Oct 15, 2017 • edited Loading

Codecov Report

AlejandroME commented Oct 27, 2017

LukaJCB commented Oct 27, 2017

rossabaker 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

AlejandroME Oct 27, 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

AlejandroME Oct 27, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AlejandroME commented Nov 6, 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

rethab commented Nov 14, 2017

AlejandroME commented Nov 20, 2017

kailuowang commented Dec 27, 2017

First approach to `NonEmptyList` docs #1971

First approach to `NonEmptyList` docs #1971

codecov-io commented Oct 15, 2017 •

edited

Loading

AlejandroME Oct 27, 2017 •

edited

Loading

AlejandroME Oct 27, 2017 •

edited

Loading