#417 :: Improve documentation about ZLayer #4431

timrourke · 2020-11-22T05:33:45Z

This PR makes some improvements to the documentation around ZLayer.

Cleans up a few minor grammatical errors and awkward bits
Attempts to make some concepts slightly more clear to newcomers
Adds links to code to facilitate deep dives on technical concepts

CLAassistant · 2020-11-22T05:33:50Z

All committers have signed the CLA.

Fix stray curly brace (zio#417)

timrourke · 2020-11-22T15:00:41Z

The tests that failed here are unrelated to my diff, are they potentially flaky tests?

In the second case, it looks like a failure came from a timeout during test execution:

Too long with no output (exceeded 10m0s): context deadline exceeded

Edit: Looks like after the CI build was retriggered, the tests cleared up.

adamgfraser

Thanks for your work on this! Very cool adding the links to the source code like this. Left some more specific comments but always great to improve documentation!

adamgfraser · 2020-11-24T03:55:09Z

docs/datatypes/zlayer.md

-    zio.provideLayer(nameLayer).as(ExitCode.success)
-
+  // Define our simple ZIO program
  val zio = for {


Adding a type signature here would be helpful.

adamgfraser · 2020-11-24T03:56:29Z

docs/datatypes/zlayer.md

  } yield ()

-  val nameLayer = ZLayer.succeed("Adam")}
+  // Create a ZLayer that exposes a string as a dependency to a ZIO program


I wouldn't say that the layer exposes a string as the dependency. The type signature of the program above and the use of access expose the string as a dependency. The layer produces a string and can be used to satisfy the dependency that the program has.

This is an important distinction! Thanks for explaining that

adamgfraser · 2020-11-24T03:56:51Z

docs/datatypes/zlayer.md


-  val nameLayer = ZLayer.succeed("Adam")}
+  // Create a ZLayer that exposes a string as a dependency to a ZIO program
+  val nameLayer = ZLayer.succeed("Adam")


Type signature would help here as well.

adamgfraser · 2020-11-24T03:59:47Z

docs/datatypes/zlayer.md

+
+ In this example, we can see that `ModuleC` depends upon `ModuleA`, `ModuleB`,
+ and `Clock`. The layer provided to the runnable application shows how
+ dependency layers that are siblings can be combined using `++` into a single


I might not use the concept of "siblings" here since it is a new concept that hasn't been defined and the layers don't have to have any relationship. We can just say that ++ lets us combine two layers to get a new layer that produces both of their outputs.

adamgfraser · 2020-11-24T04:01:13Z

docs/datatypes/zlayer.md

+ dependency layers that are siblings can be combined using `++` into a single
+ combined layer, and then can be provided together as the dependency for another
+ layer.
+


Minor comment and I realize it was already this way but shouldn't each of these paragraphs be a single line of markdown and then they will be rendered based on the screen versus us manually adding all these line breaks? I feel like this is going to make it look weird and bad on some screens.

@adamgfraser do you mean in an editor, or when the markdown is rendered to HTML? FWIW, "weird and bad" is subjective, but I'd like to know what you mean.

It looks perfectly fine in my editor, and markdown renderers will usually ignore line breaks that are not explicitly followed by a space character and combine them into a single <p> tag.

I tend to prefer keeping my code to <= 80 chars wide because it makes the code easier to see in a small screen context, or when I have a split-screen view of some code. I don't own the coding styles for ZIO, of course, so I have no real iron in this fire.

I will update my PR to make every paragraph a single line of markdown, let me know if that is what you would prefer.

@adamgfraser I've only updated the whitespace of paragraphs that I added as entirely new paragraphs to avoid code churn. I think it's worthwhile to adopt a consistent code formatting convention for markdown if possible. I know little about the options but they exist:

https://github.com/markdownlint/markdownlint

https://github.com/DavidAnson/markdownlint

If that seems reasonable, let me know. If we can identify a consensus on formatting markdown I can try to tackle this. Would probably be ideal to unify the formatting of all markdown in a single commit to avoid whitespace commit noise.

Maybe it doesn't make that much of a difference. I was worried that manually adding those breaks could for example result in line breaks being inserted too early on wide screens but maybe that is dealt with separately. Looking through the rest of the documentation it looks like one line per paragraph is more common but it is not completely consistent. Anyway, thanks for all your work on this. Will merge when it passes CI.

Thanks! I'm all for one-line-per-paragraph. I've seen folks using dedicated markdown editors (as opposed to something IDE-like) and in that context especially that is a much more natural way to format the text.

adamgfraser · 2020-11-24T04:04:25Z

docs/howto/use_modules_and_layers.md

 ```

-Then, we define another module to perform some basic logging. We provide also a `consoleLogger` implementation that relies on zio `Console`
+Then, we define another module to perform some basic logging. We provide also a `consoleLogger` implementation that relies on Zio's `Console`:


Suggested change

Then, we define another module to perform some basic logging. We provide also a `consoleLogger` implementation that relies on Zio's `Console`:

Then, we define another module to perform some basic logging. We provide also a `consoleLogger` implementation that relies on ZIO's `Console`:

adamgfraser · 2020-11-24T04:04:58Z

docs/howto/use_modules_and_layers.md


 ## Updating local dependencies
-Given a layer, it is possible to update one or more components it provides. One way is through a function to replace an old service with new service
+Given a layer, it is possible to update one or more components it provides. The `.update` method allows us to replace one


Suggested change

Given a layer, it is possible to update one or more components it provides. The `.update` method allows us to replace one

Given a layer, it is possible to update one or more components it provides. The `update` method allows us to replace one

adamgfraser · 2020-11-24T04:17:37Z

docs/howto/use_modules_and_layers.md


 ## Layers are shared in the dependency graph
-One important feature of `ZIO` layers is that they are acquired in parallel wherever possible, and they are shared. For every layer in our dependency graph, there is only one instance of it that is shared between all the layers that depend on it. If you don't want to share a module, create a fresh, non-shared version of it through `ZLayer.fresh`.
+One important feature of `ZIO` layers is that they are acquired in parallel wherever possible, and they are shared. For every layer in our dependency graph, there is only one instance of it that is shared between all the layers that depend on it. If you don't want to share a module, create a fresh, non-shared version of it through [`ZLayer.fresh`][ZLayer.fresh].


Normally we would use # for methods on a trait and . for methods on the companion object.

Just so I'm clear, what is the semantic distinction? Not disagreeing, curious. Is it about making it clear that one thing is a method call on a concrete implementation, and another is a call on something that may not be concrete? (In this case ZLayer is a sealed abstract class, not a trait, but I assume this is what you mean?)

It is more that there are cases where the same method name is used on both a type and its companion object. For example, there is a unit method on the ZIO trait that transforms the result type to Unit so you could do promise.succeed(()).unit (ignoring the Boolean value returned by succeed indicating whether the promise had already been completed). There is also a unit method on the ZIO companion object that just constructs an effect that succeeds with the unit value. So it is useful to be able to distinguish between the two when talking about them.

adamgfraser

Thanks again for your work on this! Great improvements!

* Improve documentation about ZLayer (zio#417) Fix stray curly brace (zio#417) * Adopt project conventions and improve clarity of docs (zio#417)

timrourke force-pushed the feature/417-improve-microsite-zlayer branch 2 times, most recently from 1a71e4f to 5140bc6 Compare November 22, 2020 05:44

Improve documentation about ZLayer (zio#417)

044fd72

Fix stray curly brace (zio#417)

timrourke force-pushed the feature/417-improve-microsite-zlayer branch from 5140bc6 to 044fd72 Compare November 22, 2020 14:20

timrourke mentioned this pull request Nov 22, 2020

Flaky test for ZQueue? #4436

Closed

adamgfraser suggested changes Nov 24, 2020

View reviewed changes

Adopt project conventions and improve clarity of docs (zio#417)

5606ac8

timrourke requested a review from adamgfraser November 25, 2020 14:26

adamgfraser approved these changes Nov 25, 2020

View reviewed changes

adamgfraser merged commit cf25ac7 into zio:master Nov 25, 2020

timrourke deleted the feature/417-improve-microsite-zlayer branch November 26, 2020 00:00

	Then, we define another module to perform some basic logging. We provide also a `consoleLogger` implementation that relies on Zio's `Console`:
	Then, we define another module to perform some basic logging. We provide also a `consoleLogger` implementation that relies on ZIO's `Console`:

	Given a layer, it is possible to update one or more components it provides. The `.update` method allows us to replace one
	Given a layer, it is possible to update one or more components it provides. The `update` method allows us to replace one

Uh oh!

#417 :: Improve documentation about ZLayer #4431

#417 :: Improve documentation about ZLayer #4431

Uh oh!

Conversation

timrourke commented Nov 22, 2020

Uh oh!

CLAassistant commented Nov 22, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

timrourke commented Nov 22, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adamgfraser left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamgfraser left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

CLAassistant commented Nov 22, 2020 •

edited

Loading

timrourke commented Nov 22, 2020 •

edited

Loading