https://bugzilla.redhat.com/show_bug.cgi?id=990423
--- Comment #3 from Michael Schwendt bugs.michael@gmx.net --- As this ticket comes flying by, here are only a few comments on documentation quality related issues.
Summary: A fork of NaCl library with compatible APIs
That's details the %description can explain.
You want the %summary to be more like a list of keywords a developer might search for (e.g. "networking", "cryptography"). Here is not much to find yet, unless the developer happens to know what "NaCl" refers to and that it doesn't refer to "sodium chloride" or "Google Native Client".
Making the summary more generic would be much better. Upstream github page calls it a "crypto library", for example (and it's okay that the advertise it being a fork, but that doesn't belong into Fedora's package summary). NaCl is short for
Summary: Networking and cryptography library
or if it needs to be a bit more verbose:
Summary: Library for network communication cryptography
%description NaCl (pronounced "salt") is a new easy-to-use high-speed software library [...]
Why does it start with expanding what "NaCl" means? It should start with explaining what it does or what it is. Currently, the description is the same as in package "nacl":
# yum info nacl|tail -5 Description : NaCl (pronounced "salt") is a new easy-to-use high-speed software : library for network communication, encryption, decryption, : signatures, etc. NaCl's goal is to provide all of the core : operations needed to build higher-level cryptographic tools.
So:
%description This is "Sodium", a portable, cross-compilable, installable, packageable networking and cryptography library. Its goal is to provide all of the core operations needed to build higher-level cryptographic tools.
It is a fork of "NaCl" (Networking and Cryptography library), with a compatible API.
%doc ChangeLog
It only says "git log is your friend.", which is less useful than a link to the upstream github log. Hence I would not include this file.
%doc README
It only says "See README.markdown", which is not included. It exists in upstream git, however.
%doc
There is no API documentation yet?