[Haskell-cafe] Hackage package "synopsis" sections

[Dominick Samperi]

For an example of this kind of policy see the R system. Here the
final check issues warnings when exported functions are not
documented. This strategy is not perfect as a submitter can always
provide dummy docs that keep the checker quiet but do not provide
much assistance to the end user.

On the other hand, R functions tend to be documented well,
and almost always include working examples
in the help page that can be run from the command prompt via:
help(function-name).


On Tue, Sep 16, 2014 at 5:10 PM, Richard Lewis <richard at rjlewis.me.uk> wrote:
> So there's clearly an important technical hurdle to be overcome for
> this: what markup language is to be used?; and where should the
> synposis be stored?
>
> But I can't help thinking that the real work is in getting the
> synopses written. Encouraging package authors/maintainers to add them
> to their own packages is one possible way forward.
>
> At Mon, 15 Sep 2014 11:28:38 -0700,
> Tikhon Jelvis wrote:
>
>> Maybe we could have a guerrilla campaign of pull requests adding
>> examples and a bit of explanation to every package you like that
>> doesn't have them... That could also be a good way for beginners who
>> want to contribute to start.
>
> Another, as Tikhon suggests, would be for others to write them and
> send pull requests (or whatever) to the maintainers.
>
> At Mon, 15 Sep 2014 20:10:18 -0400,
> Dominick Samperi wrote:
>
>> I think this is a great idea, but it probably needs a complementary
>> "nudge" if it is going to have a significant impact. This could be
>> incorporated into the package submission process where the submitter
>> runs a final check and is warned when examples are not provided for
>> exported functions (unless an "opt out" flag is turned on for
>> functions that have "obvious" semantics).
>
> And yet another, as Dominick suggests, is effectively to require a
> synposis when a package is submitted. In CPAN, it's just become part
> of the culture, but it's also not required and you do find packages
> without a synposis.
>
> If there's interest, I'd like to solicit some discussion on this part
> of the proposal on this thread...
>
> There may also be a potentially significant difference between
> Hackage/Haskell and CPAN/Perl: most CPAN packages tend to be quite
> small and specific in their purpose and consequently have just a few,
> simple common use cases which suit a synposis very well. Hackage
> packages, on the other hand, are quite often more broad in their
> scope, often comprising many modules. Also, Perl has only one
> semantics for organising code at the finest level: sequential,
> imperative statements. In Haskell, some packages actually define whole
> coding styles. As a result, it's always pretty obvious how to write a
> few isolated lines of Perl code, but not necessarily so with Haskell
> code. Anyway, I'm sure all this can be overcome, and/or argued
> against.
>
> Richard
> --
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> Richard Lewis
> j: ironchicken at jabber.earth.li
> @: lewisrichard
> http://www.richardlewis.me.uk/
> -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
> _______________________________________________
> Haskell-Cafe mailing list
> Haskell-Cafe at haskell.org
> http://www.haskell.org/mailman/listinfo/haskell-cafe