Cabal: Can the description field be optional?

[ivan-m]

I've just received a warning from trying to run cabal check using GHC/cabal HEAD that my description isn't longer than my synopsis.

The problem is that a lot of libraries tend to be ones along the form of "Make foo and bar talk to each other."; as such, unless I wanted to talk about what foo and bar are, there is not much I can really talk about there (except possibly repeat all the functions that are found in the Haddock docs).

As such, would it be possible for Cabal to _not_ require the description field? I've found in practice that it's either not much more than a re-worded version of the synopsis or that it's so long that it means I have to scroll the Hackage page before I can view what I actually want (typically the Haddock pages).

[hvr]

Being the one who created the warning you now see, I claim that such cases are the minority, and that the overall benefit for Hackage outweighs the inconvenience for those few cases where you really can't come up with a full paragraph of things to you'd want to say about your package. It would help if you could point me to concrete examples on Hackage.

See also this posting for more on the relationship on synopsis/description/README.

[ivan-m]

This is a library I uploaded recently.

If you know what streaming and conduit are, then just the package name/synopsis suffices. If you don't, then whilst I could put more details into the description, that's the task of those packages themselves.

The description could cover the functions available... but that's the job of the Hackage docs.

[23Skidoo]

@ivan-m I think a good start would be to repeat what you said in the "Motivation" section of the README.

[ivan-m]

@23Skidoo see, I put that in there just to bulk out the README a bit so it didn't look so plain on GitHub and also link to some other libraries.

Again, I think it's primarily a case that the synopsis of "Bidirectional support between the streaming and conduit libraries" covers completely what it does, and the Hackage docs cover the specifics of how to do it; anything else I put either in the description or the README is just filler faff rather than actually adding any value.

[phadej]

I tend to disagree, description really adds value.

Compare:

---

EDIT: It's hard to write good description, as it is writing good documentation. That's not the reason to not have one. Making description optional won't help with "Haskell libraries tend to have poor documentation" semi-myth. IMHO.

---

If nothing else, convert the streaming and conduit into links in the description (description field is rendered using haddock syntax - than it will be longer and more useful!

[23Skidoo]

@ivan-m I disagree :) I found the README you wrote useful, even though I know what the streaming and conduit packages do (and for someone who doesn't, it saves a few clicks). Phrases like "interoperability" and "bidirectional support" are somewhat general/broad, so it's nice when the package author explains in English what they mean in current context. If you're completely out of ideas what to put in the description, I'd suggest a small code example with an explanation. E.g.:

Convert your Streams to Conduits and vice versa with one line of code:

conduit = fromStream stream
stream  = toStream conduit

[23Skidoo]

Closing as wontfix.