New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add haddocks for capabilities #33

Merged

aherrmann merged 6 commits into master from haddock-laws

Sep 25, 2018

Member

aherrmann commented Sep 5, 2018 •

edited

Loading

~~Question: Is there an authoritative source for the laws? (See mtl issue linked from the diff)~~

Adds haddock documentation for capability classes and their methods.
Adds (not yet definitive) laws based on the discussion in Missing laws haskell/mtl#5.
Documents sources for laws in LOG.md.

Member Author

aherrmann commented Sep 5, 2018

Define the reader and state laws in terms of ask,local; get,`put.

Add a LOG.md listing sources for the laws.

Document that these are not necessarily definitive.

aherrmann requested a review from aspiwack as a code owner

September 21, 2018 13:10

aherrmann changed the title ~~[WIP] Add haddocks for capabilities~~ Add haddocks for capabilities

aherrmann requested a review from mboes

September 24, 2018 08:37

aspiwack requested changes

View reviewed changes

Member

aspiwack left a comment

I posit that we can do much better. Sorry to push this on you so late.

I've gone through the Reader haddock strings. This should give you enough material to go update the rest.

src/HasReader/Internal/Class.hs Outdated

               class Monad m
                 => HasReader (tag :: k) (r :: *) (m :: * -> *) | tag m -> r
                 where
+                  -- | Use 'ask' instead.

Member

aspiwack Sep 24, 2018

« For technical reasons, this method needs an extra proxy argument. You only need if you are defining new instances of 'HasReader'. In other case, you will want to use 'ask'. See 'ask' for more documentation. »

(and similarly on all the methods. I know it's a bit tedious, but it is absolutely worth it)

src/HasReader/Internal/Class.hs Outdated

                   reader_ :: Proxy# tag -> (r -> a) -> m a
+              -- | @ask \@tag@
+              -- Retrieve the environment.

Member

aspiwack Sep 24, 2018

« retrieves » (final s, no capital letters).

I'd even put it like this: « @ask \@tag@ retrieves the environment of the reader capability @\@tag@. »

src/HasReader/Internal/Class.hs Outdated

               ask :: forall tag r m. HasReader tag r m => m r
               ask = ask_ (proxy# @_ @tag)
               {-# INLINE ask #-}
+              -- | @asks \@tag@
+              -- Retrieve a projection of environment according to @f@.

Member

aspiwack Sep 24, 2018

How about @asks \@tag f = f <$> ask \@tag@ ? It's quite a bit less confusing. I'm not sure that there is a way to clarify further.

An English translation of this would be « @asks \@tag f@ retrieves the image, by @f@ of the environment of the reader capability @\@tag@. » You can have this. But the straightfoward definition should definitely be there too.

src/HasReader/Internal/Class.hs Outdated

+              -- | @asks \@tag@
+              -- Retrieve a projection of environment according to @f@.
+              --
+              -- XXX: Seems identical to 'reader'. Is 'asks' redundant?

Member

aspiwack Sep 24, 2018

No XXX in haddock comments. But yes, it's the same as reader, though their intent is a bit different. In fact, in the mtl, asks is defined as reader.

src/HasReader/Internal/Class.hs Outdated

               asks :: forall tag r m a. HasReader tag r m => (r -> a) -> m a
               asks f = f <$> ask @tag
               {-# INLINE asks #-}
+              -- | @local \@tag f m@
+              -- Execute @m@ with the environment updated according to @f@.

Member

aspiwack Sep 24, 2018

« @local \@tag f m@ runs the monadic action @m@ in a modified environment @e' = f e@, where @e@ is the environment of the reader capability @\@tag@. Symbolically: @return e = ask \@tag@. »

src/HasReader/Internal/Class.hs Outdated

               local :: forall tag r m a. HasReader tag r m => (r -> r) -> m a -> m a
               local = local_ (proxy# @_ @tag)
               {-# INLINE local #-}
+              -- | @reader \@tag@

Member

aspiwack Sep 24, 2018

@reader \@tag act@ lifts a purely environment-dependent action @act@ to a monadic action in an arbitrary monad @m@ with capability @HasReader@.

It happens to coincide with @asks@: @reader = asks@.

aherrmann added 5 commits

September 25, 2018 10:41


          Add haddocks for capabilities

7b46fe4


          Update laws where available

8ffa155


          Write to LOG.md about laws

2d04867


          Apply aspiwack's comments to HasReader

f81afaa


          Apply aspiwack's comment to the remaing

6103eb4

aherrmann force-pushed the haddock-laws branch from 7f45927 to 6103eb4 Compare

September 25, 2018 08:58

Member Author

aherrmann commented Sep 25, 2018

@aspiwack Ready for another round.

aspiwack approved these changes

View reviewed changes

Member

aspiwack left a comment

Minor changes below. Then merge.

src/Capability/Reader/Internal/Class.hs Outdated

               ask :: forall tag r m. HasReader tag r m => m r
               ask = ask_ (proxy# @_ @tag)
               {-# INLINE ask #-}
+              -- | @asks \@tag@
+              -- retrieves the image, by @f@ of the environment

Member

aspiwack Sep 25, 2018

no comma here.

src/Capability/State/Internal/Class.hs Outdated

                   state_ :: Proxy# tag -> (s -> (a, s)) -> m a
+              -- | @get \@tag@
+              -- retrieve the current state of the state capability @\@tag@.

Member

aspiwack Sep 25, 2018

I just realised that in this phrasing, we should say the state capability @tag@ without the \@. We should clean that everywhere, I suppose.

src/Capability/State/Internal/Class.hs Outdated

               state :: forall tag s m a. HasState tag s m => (s -> (a, s)) -> m a
               state = state_ (proxy# @_ @tag)
               {-# INLINE state #-}
+              -- | @modify \@tag f@
+              -- given the current state @s@ of the state capability @\@tag@
+              -- and @s' = f s@, update the state to @s'@.

Member

aspiwack Sep 25, 2018

update -> updates.
By symmetry: update the state of the capability @tag@.

src/Capability/State/Internal/Class.hs Outdated

               modify' :: forall tag s m. HasState tag s m => (s -> s) -> m ()
               modify' f = do
                 s' <- get @tag
                 put @tag $! f s'
               {-# INLINE modify' #-}
+              -- | @gets \@tag f@
+              -- retrieves the image, by @f@ of the current state
+              -- of the state capability @\@tag@.

Member

aspiwack Sep 25, 2018

Add the definitional rule in terms of get like in reads.

src/Capability/Stream.hs Outdated

                   yield_ :: Proxy# tag -> a -> m ()
-              -- | Emit the given value.
+              -- | Emit the given value in the given stream capability.

Member

aspiwack Sep 25, 2018

As usual @yield \@tag a@ emits @a@ in the stream capability @tag@.

src/Capability/Writer.hs Outdated

                   pass_ :: Proxy# tag -> m (a, w -> w) -> m a
+              -- | @writer \@tag (a, w)@
+              -- writes @w@ to the output of the writer capability @\@tag@

Member

aspiwack Sep 25, 2018

This should be « lifts a pure, etc… »

src/Capability/Writer.hs Outdated

               writer :: forall tag w m a. HasWriter tag w m => (a, w) -> m a
               writer = writer_ (proxy# @_ @tag)
               {-# INLINE writer #-}
+              -- | @tell \@tag w@
+              -- writes @w@ to the output of the writer capability @\@tag@.

Member

aspiwack Sep 25, 2018

not « writes »: appends. Since it is the word used in Haskell for monoid thingies.

src/Capability/State/Internal/Class.hs Outdated

               put :: forall tag s m. HasState tag s m => s -> m ()
               put = put_ (proxy# @_ @tag)
               {-# INLINE put #-}
+              -- | @state \@tag f@
+              -- given the current state @s@ of the state capability @\@tag@
+              -- and @(a, s') = f s@, update the state to @s'@ and return @a@.

Member

aspiwack Sep 25, 2018

This should be « lifts a pure, yada yada ».

src/Capability/Writer.hs Outdated

               tell :: forall tag w m. HasWriter tag w m => w -> m ()
               tell = tell_ (proxy# @_ @tag)
               {-# INLINE tell #-}
+              -- | @listen \@tag m@
+              -- executes the action @m@ and returns the output of @m@
+              -- in the writer capability @\@tag@ along with result of @m@.

Member

aspiwack Sep 25, 2018

What does it output? The output of @m@? mempty?

src/Capability/Writer.hs Outdated

+              -- | @pass \@tag m@
+              -- executes the action @m@. Assuming @m@ returns @(a, f)@ and writes
+              -- @w@ to the output of the writer capability @\@tag@.
+              -- @pass \@tag m@ instead writes @w' = f w@ to the output and returns @a@.

Member

aspiwack Sep 25, 2018

writes -> appends


          Address aspiwack's comments

ec0665b

aherrmann merged commit 5cf9a8a into master

aherrmann deleted the haddock-laws branch

September 25, 2018 13:43

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet