Docs for Func and AppFunc #4378

UlisesTorrella · 2023-01-19T12:49:42Z

Hi! This pr closes issue 2650.
I tried to keep it simple, since most of the concepts are explained in the Applicative page.
I added some comments whilst I was trying to understand the code. Let me know if anything is wrong, I'm not an expert, so perhaps I got something mixed up.

johnynek · 2023-01-19T17:30:13Z

I think the doc needs to start with the fact that shape looks almost identical to Kleisli and explain how they are different.

The issue links to a blog post and explains it and maybe we can just reuse some of the explanation. A very short summary may be that Kleisli is about sequential composition of functions while Func (poorly named) is about parallel compositions of functions.

I appreciate your PR, but I think re-explaining other core typeclasses (Applicative, Traverse) shouldn't go in here.

UlisesTorrella · 2023-01-19T19:23:21Z

I was hesitant to mention that. I had written something about it, but though that, given that AppFunc is "more general" than Kleisli it would be confusing to mention Kleisli for someone unfamiliar to it.
But you are right, if it was discussed in the issue is because it's a point of confusion. I'll include it. Should it start the doc? or start the "AppFunc" section?

UlisesTorrella · 2023-01-20T11:03:34Z

Ok, I mentioned the similarities with Kleisli and removed over explanation of traverse, just left the link to the applicative docs and an example

reardonj

docs/datatypes/directory.conf needs to be updated with a reference to this page.

I left some small fixup suggestions as well, but I have to wonder if this article would be more useful if it started by introducing AppFunc directly, then discussing Func as a weaker version after (similar to how Apply is described in the Applicative article). With the current version, the motivation for caring (how to: compose applicative functors), is buried really deep.

docs/datatypes/func.md

reardonj · 2023-02-22T01:02:25Z

docs/datatypes/func.md

@@ -0,0 +1,78 @@
+# Func


A link to the scaladoc should be added now that #4401 is merged.

docs/datatypes/func.md

reardonj · 2023-02-22T01:45:50Z

docs/datatypes/func.md

@@ -0,0 +1,78 @@
+# Func


Since AppFunc is so important here, maybe the title should be "Func and AppFunc"? Some of the typeclasses are done this way.

reardonj · 2023-02-22T01:47:00Z

docs/datatypes/func.md

+
+# AppFunc 
+
+AppFunc extends Func to wrap around a special type of functor: Applicative functors.


May as well link to the section for reference.

Suggested change

AppFunc extends Func to wrap around a special type of functor: Applicative functors.

AppFunc extends Func to wrap around a special type of functor: [Applicative] functors.

docs/datatypes/func.md

reardonj · 2023-02-22T02:07:36Z

docs/datatypes/func.md

+
+Signature: `AppFunc[F[_], A, B] extends Func[F, A, B]` 
+
+Now, for the reader familiar with `Kleisli`, we find an even more similar data type. `AppFunc` provides compositions of weaker constraint, allowing to compose `AppFunc[F[_], A, B]` with `AppFunc[G[_], C, A]`.   


I don't think these Kleisli call outs are going to help people trying to figure out what AppFunc is for. Have you considered having a comparison to Kleisli section at the end of the article?

Hey, yes actually I think at the beginning it was at the end but a suggestion was to move it to the beginning. Given that most doubts in the PR introducing the code were around "why do we need this if Kleisli is a thing"

Ha, I guess that's down to a matter of audience. For cats newcomers, Kleisli is probably at least as foreign as this.

Co-authored-by: Justin Reardon <me@jmreardon.com>

UlisesTorrella · 2023-03-04T18:43:53Z

docs/datatypes/directory.conf needs to be updated with a reference to this page.

I left some small fixup suggestions as well, but I have to wonder if this article would be more useful if it started by introducing AppFunc directly, then discussing Func as a weaker version after (similar to how Apply is described in the Applicative article). With the current version, the motivation for caring (how to: compose applicative functors), is buried really deep.

Hey, I saw your suggestions and applied almost all, only question the one about Kleisli, let me know what you think.
Also updated the branch and incluede docs links

reardonj

Now that I've read it, the new Kleisli text gives enough context to not feel out of place at the start.

reardonj · 2023-03-04T19:18:17Z

docs/datatypes/func.md

+
+Func is a wrapper around a `run` function `A => F[B]` where `F` is a functor. Given that, the Func data type is equipped with the known `map` function, and a `mapK` function to apply natural transformations (from a `Func[F[_], A, B]` get an `Func[G[_], A, B]`).
+
+The signature `Func[F[_], A, B]` is very similar to the signature for [Kleisli](../datatypes/kleisli.md): `Kleisli[F[_], -A, B]`. The difference is that `Func` is a less restrictive data type that wraps around functors, and only provides basic methods `run`, `map`, and `mapK`, while `Kleisli` is strong enough to provide composition, flatMap, and more. We will see a more useful data type just next with `AppFunc`. 


Does just [Kleisli] without an explicit link not work?

Nope, I got an exception when running the preview. I got this explicit from another doc doing the same, must be for the same reason. Idk why it says the Klesli reference is "ambiguous"

Wierd. Too bad. Maybe 2 sections called "Kleisli" somewhere?

docs/datatypes/func.md

UlisesTorrella added 5 commits January 16, 2023 15:44

a bit of comentary on data.Func

deb9ee3

first draft

7954176

func and appfunc datatype docs

e0999bf

renaming and adding a link to AppFunc doc

6036cdd

bit of rewording in AppFunc docs

700099b

corrections to Func docs

a029422

UlisesTorrella marked this pull request as ready for review January 20, 2023 13:15

reardonj reviewed Feb 22, 2023

View reviewed changes

UlisesTorrella and others added 9 commits March 4, 2023 18:57

Update docs/datatypes/func.md

2cebdb6

Co-authored-by: Justin Reardon <me@jmreardon.com>

Update docs/datatypes/func.md

b8613ff

Co-authored-by: Justin Reardon <me@jmreardon.com>

Update docs/datatypes/func.md

06def49

Co-authored-by: Justin Reardon <me@jmreardon.com>

refactor in Func documentation capitalized vals

e73fe8e

Update docs/datatypes/func.md

0ea4eff

Co-authored-by: Justin Reardon <me@jmreardon.com>

Update docs/datatypes/func.md

aee7268

Co-authored-by: Justin Reardon <me@jmreardon.com>

Include AppFunc in the Func documentation

5b0faa9

Merge branch 'main' into doc-for-func

9e91be0

include links in Func docs and added my name to contributors

1af3c3b

reardonj reviewed Mar 4, 2023

View reviewed changes

link to nested

c815fe0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs for Func and AppFunc #4378

Docs for Func and AppFunc #4378

UlisesTorrella commented Jan 19, 2023

johnynek commented Jan 19, 2023

UlisesTorrella commented Jan 19, 2023

UlisesTorrella commented Jan 20, 2023

reardonj left a comment

reardonj Feb 22, 2023

reardonj Feb 22, 2023

reardonj Feb 22, 2023

reardonj Feb 22, 2023

UlisesTorrella Mar 4, 2023

reardonj Mar 4, 2023

UlisesTorrella commented Mar 4, 2023 •

edited

reardonj left a comment

reardonj Mar 4, 2023

UlisesTorrella Mar 4, 2023

reardonj Mar 4, 2023


		# AppFunc

		AppFunc extends Func to wrap around a special type of functor: Applicative functors.


		Signature: `AppFunc[F[_], A, B] extends Func[F, A, B]`

		Now, for the reader familiar with `Kleisli`, we find an even more similar data type. `AppFunc` provides compositions of weaker constraint, allowing to compose `AppFunc[F[_], A, B]` with `AppFunc[G[_], C, A]`.


		Func is a wrapper around a `run` function `A => F[B]` where `F` is a functor. Given that, the Func data type is equipped with the known `map` function, and a `mapK` function to apply natural transformations (from a `Func[F[_], A, B]` get an `Func[G[_], A, B]`).

		The signature `Func[F[_], A, B]` is very similar to the signature for [Kleisli](../datatypes/kleisli.md): `Kleisli[F[_], -A, B]`. The difference is that `Func` is a less restrictive data type that wraps around functors, and only provides basic methods `run`, `map`, and `mapK`, while `Kleisli` is strong enough to provide composition, flatMap, and more. We will see a more useful data type just next with `AppFunc`.

Docs for Func and AppFunc #4378

Are you sure you want to change the base?

Docs for Func and AppFunc #4378

Conversation

UlisesTorrella commented Jan 19, 2023

johnynek commented Jan 19, 2023

UlisesTorrella commented Jan 19, 2023

UlisesTorrella commented Jan 20, 2023

reardonj 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

UlisesTorrella commented Mar 4, 2023 • edited

reardonj 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

UlisesTorrella commented Mar 4, 2023 •

edited