On Fri, Apr 07, 2006 at 11:32:38 -0700, Jason Dagit wrote: > > > + -> Bool -- ^ working directory - if True, this means some > > > inconsitencies such > > > + -- as removing a non-empty directory are treated as > > > warnings, not > > > + -- errors. When in doubt, set to False.
> > I prefer comments to be separated from the type, so that the type > > remains compact and easily readable. But that's just me. > In conclusion, I'd say Eric commented it the right > way in this case. :) Come to think of it, the way I did it would probably haddock very badly. A function-level comment would probably be more readable, both in the code and the resulting haddock. See showTreeWith http://www.haskell.org/ghc/docs/latest/html/libraries/base/Data-Map.html Hence, my attempt to imitate the haskell library (will submit): -- | Note: The expression (@apply flags working p@) applies the patch -- to whatever directory-like monad you are in. If @working@ is -- 'True', some inconsitencies such as removing a non-empty directory -- are treated as warnings, not errors. When in doubt, set @working@ -- 'False'. apply :: WriteableDirectory m => [DarcsFlag] -> Bool -- ^ working directory -> Patch -> m () I hope I actually learn how to write good comments and API doc one day, and better yet, code which is so clear you don't even need comments. -- Eric Kow http://www.loria.fr/~kow PGP Key ID: 08AC04F9 Merci de corriger mon français.
pgpZUqLV6Apaj.pgp
Description: PGP signature
_______________________________________________ darcs-devel mailing list [email protected] http://www.abridgegame.org/cgi-bin/mailman/listinfo/darcs-devel
