On Mon, 2011-09-05 at 15:42 +0200, Joachim Breitner wrote: > Hi, > > Am Montag, den 05.09.2011, 14:24 +0100 schrieb Iulian Udrea: > > On Mon, 2011-09-05 at 14:18 +0200, Joachim Breitner wrote: > > > Am Montag, den 05.09.2011, 10:21 +0000 schrieb Iulian Udrea: > > > > +Description: HTTP client package with enumerator interface and HTTPS support > > > > + This package uses attoparsec for parsing the actual contents of the HTTP > > > > + connection. The only gotcha is the withHttpEnumerator function, otherwise > > > > + should do exactly what you expect. > > > > + . > > > > + This package provides a library for the Haskell programming language. > > > > + See http://www.haskell.org/ for more information on Haskell. > > > > > > thanks for the package. May I ask you come up with a good description > > > before I upload? Especially the sentence about the gotcha is > > > incomprehensible (and even reading the module documentation does not > > > explain what gotcha there is, nor what that function is). > > > > The description has been copied verbatim from the cabal file. This > > library is a dependency of yesod 0.8.2.1 which we're trying to get in. I > > haven't looked at the source as I don't have any particular interests in > > the library and hence I don't know what the withHttpEnumerator function > > does. > > I know this dilemma (and Haskell projects tend to have a lot of small > dependencies). But just like a good copyright file, this is something > that just has to be done to keep up the quality of packages in Debian, > even if it is sometime annoying. Indeed. > > I found "This module contains everything you need to initiate HTTP > > connections. Make sure to wrap your code with 'withHttpEnumerator'." but > > as you said it doesn't tell anything useful about withHttpEnumerator. > > It seems that this used to be part of the API, and the description is > not up-to-date, 0.3.1 still had the function: > http://hackage.haskell.org/packages/archive/http-enumerator/0.3.1/doc/html/Network-HTTP-Enumerator.html#v:withHttpEnumerator > > > What do you think of replacing "The only gotcha is the > > withHttpEnumerator function, otherwise should do exactly what you > > expect." with "This module contains everything you need to initiate HTTP > > connections."? Does that make sense to you? At least when someone > > apt-cache searches for "http connection", the library will show up. > > Yes, that would be a sufficient start. You could also notify Michael > Snoyman about the outdated description and tell him that an expanded > package description would be appreciated. The more Hackage package > authors know that we care about the description, the better are the > chances that we really can copy’n’paste them :-). That's true. Also, if the maintainers aren't familiar with the code and the description of the library is poor, then they will definitely write something which is either incorrect or incomprehensible. Therefore, in these situations I personally prefer to keep it simple instead of writing something which doesn't make sense whatsoever, just for the sake of complying with the policy. There are of course other ways to resolve this issue but that might take some time and we don't want to keep a library out of the archive just because the description of the package is poor. In the end, if the user of the library wants to find out more about it, then s/he will end up with the same poor description upstream as well. > I think I’ll send a mail to haskell-cafe about that as well. Are you > subscribed to that list? That would indeed be a great thing to do. And yes, I am. Cheers, -- Iulian Udrea iulian@linux.com
Attachment:
signature.asc
Description: This is a digitally signed message part