On 06/30/2014 04:19 PM, Richard Eisenberg wrote:
Thanks, Johan, for starting this discussion.
I mostly agree with the proposal. However, one (at times, serious) drawback
to using Haddock is that it means that editing comments can cause parse
failures. The way the GHC build works, these
Agreed, let's do it. Thanks for the well-argued proposal.
Next up: consistent style :-)
Cheers,
Simon
On 27/06/2014 10:51, Johan Tibell wrote:
Hi!
I found myself exploring new parts of the GHC code base the last few
weeks (exciting!), which again reminded me of my biggest frustration
when
That has a high chance of backfiring and requiring everyone to use do {
...; ... } with explicit braces and semis. ;)
-Edward
On Wed, Jul 2, 2014 at 4:08 AM, Simon Marlow marlo...@gmail.com wrote:
Agreed, let's do it. Thanks for the well-argued proposal.
Next up: consistent style :-)
I also support this proposal (I actually tripped up on these exact
functions as well!) As stated elsewhere, I think this should be the
case for all top-level functions, not just exported ones.
Of course, I'd also like it if this rule explicitly extended to
top-level data types, type classes, etc
On Wed, Jul 2, 2014 at 6:04 PM, Austin Seipp aus...@well-typed.com wrote:
Of course, I'd also like it if this rule explicitly extended to
top-level data types, type classes, etc as well. I believe that was
the intention but I'm just making sure. :)
That was the intention.
(Finally, I
Yes, Phabricator/arcanist is probably the best way to do it, I agree.
I was more wondering technically how we'd enforce it (just regex?
parse/lex the code for top level definitions? etc). There are also
other opportunities for linting here, so we should think about that a
bit.
Anyway, good stuff!
Which makes a lot of GHC code more readable — I’m serious!
Manuel
PS: I have resisted it for a while, but after slogging through GHC for extended
periods, I’ve come to appreciate the additional clarity in large and tricky
functions (e.g., in the type checker renamer).
Edward Kmett
At the risk of sounding redundantly redundant, I'd like to third this.
My workflow for finding stuff in the GHC codebase is a mixture of grep
and Hoogle. Searching Hoogle for +ghc :: [TyVar] - Type - Type is
a huge timesaver, and Hoogle sends me to the generated haddock
comments. Usually the
Thanks, Johan, for starting this discussion.
I mostly agree with the proposal. However, one (at times, serious) drawback to
using Haddock is that it means that editing comments can cause parse failures.
The way the GHC build works, these failures may not be detected until the end
of a hacking
On Fri, Jun 27, 2014 at 11:11 AM, Mateusz Kowalczyk fuuze...@fuuzetsu.co.uk
wrote:
On 06/27/2014 03:26 PM, David Fox wrote:
I would counter propose a place on hackage for people to type in or
modify
the documentation for functions, designed in such a way that the
documentation would
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1
Hey list,
I am strongly in favour of the proposal. As a pedestrian-level GHC
contributor, the *vast* majority of my time is spent trying to figure
out what certain things do, when the answer could be found in a one-
or two-line comment above a
Richard,
Not requiring contributors to check that the Haddock render well is
OK. As long as the comments are there someone with free time on their
hands can always tidy up the rendering.
I'm looking forward to the day I can browse the GHC Haddocks and make
sense of them. I tried in the past but
Left hold off one more week to give more contributors a change to
voice their thoughts. If no one protests I will announce the new
policy next Monday. Sounds good?
___
ghc-devs mailing list
ghc-devs@haskell.org
I think that's a good idea, as long as we do enforce it as social policy
rather than a script. In other words, we should encourage folks to add
comments documenting functions, but not necessarily require them
*everywhere*, and leave it
I also share Richard's concern about using Haddock notation,
David Luposchainsky dluposchain...@googlemail.com writes:
Hey list,
I am strongly in favour of the proposal. As a pedestrian-level GHC
contributor, the *vast* majority of my time is spent trying to figure
out what certain things do, when the answer could be found in a one-
or two-line
Given the examples provided with this proposal it looks like this
change is targeted mostly at compiler hackers, and not at
library/package developers. For the latter community it would be nice
to establish a policy for libraries and packages that encourages
(nudges) developers to include comments
On Mon, Jun 30, 2014 at 11:22 PM, Dominick Samperi djsamp...@gmail.com wrote:
Given the examples provided with this proposal it looks like this
change is targeted mostly at compiler hackers, and not at
library/package developers.
Yes, this discussion is only about documenting the GHC modules.
I’d be OK with this, (it’s a bit like requiring signatures on all top level
functions) but I don’t know how we’d enforce it.
Do you think the requirement should be for all top-level functions or just
exported ones?
I agree that Notes have a different purpose. But it should be OK style to
On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton Jones
simo...@microsoft.com wrote:
I’d be OK with this, (it’s a bit like requiring signatures on all top level
functions) but I don’t know how we’d enforce it.
I think social enforcement is enough. If we agree that this is
something we want to do
I would counter propose a place on hackage for people to type in or modify
the documentation for functions, designed in such a way that the
documentation would easily find its way back into the project's source code
(with developer approval.) This way the documentation can be generated by
people
On 06/27/2014 01:19 PM, Johan Tibell wrote:
On Fri, Jun 27, 2014 at 12:17 PM, Simon Peyton Jones
simo...@microsoft.com wrote:
I’d be OK with this, (it’s a bit like requiring signatures on all top level
functions) but I don’t know how we’d enforce it.
I think social enforcement is enough.
I don't think this is mutually exclusive with Johan's proposal. Let me suggest
an amendment: Developers (both new and old) would be encouraged to submit
patches adding or improving documentation in the source code. Documentation
patches would be vetted as any others would be.
Discouraging
On 06/27/2014 03:26 PM, David Fox wrote:
I would counter propose a place on hackage for people to type in or modify
the documentation for functions, designed in such a way that the
documentation would easily find its way back into the project's source code
(with developer approval.) This way
23 matches
Mail list logo
