Real documentation

[thoughtpolice]

I'd like to document and give pointers about most of the underlying selected primitives in the haddock modules, etc. There should be real documentation/explanation if I'm to make this a good library!

[tel]

I could probably quite easily help here as well. Is there an example of some part of the documentation that you really like so far?

[thoughtpolice]

I'd like every module to at least specify the underlying primitive in the documentation. In the name of sanity, I intentionally DO NOT provide access to the alternative primitives. For example, streaming encryption is xsalsa20 only: no ability to use aes128ctr. The APIs only provide access to the default, recommended mode of operation. I did offer them all in the past but it makes the API much larger and harder to maintain. All modules should specify this, perhaps referencing individual works relating to the primitive itself if they are interested.

Furthermore I'd like doctest integration with examples in each module if possible. ekmett/lens has a pretty good doctests.hs test we could use: https://github.com/ekmett/lens/blob/master/tests/doctests.hs

Finally I need to fix the examples in the examples folder (I think the only one is broken...) I need to write more examples, too. And perhaps put a place on the wiki describing "Why would you want to use salt", and a basic field guide to use, with references elsewhere.

I want to set a high standard for documentation and coverage of this core package (typical cryptographic libraries are utterly pathetic here.) For the most part the testsuite coverage is pretty good, but the documentation is terribly lacking which is just as bad!

You don't have to do all of this, but everything is appreciated :) Please read CONTRIBUTING and just reference this issue in your commits and I think you're more than ready to go.

[tel]

I agree with being opinionated in the primitive choice—that's a huge part of the entire NaCl method, no? I'll look into doctest; I didn't even know someone had ported it to Haskell!

I could also write up some use cases for Salt as a starting point for generating documentation.

---

A lot of my interest comes from building a higher level library on these primitives which provides typesafe, multiparty-encrypted boxes like Encrypted RecordType. I'm also looking at a monadic interface for key management so that there could be some control over the pinning of the underlying keys. More to say, but I'll put that in the commentary on issue #10 probably.

[thoughtpolice]

Great! If you submit some patches I'd be more than willing to let you push directly (we can talk more about this later.) Any work here would be great.

[tel]

Doctest is absolutely a killer library. I didn't know that quickcheck property specification was allowed in Haddock comments as well. That's wonderful!

[tel]

I've written up a documentation wiki page to collect some information for this ticket. In particular, it collected some NaCl gotchas and documents the primitives used by Salt. It also importantly notes the compatibility gotcha in Crypto.NaCl.Sign.

That page will be moved to the source as well. It could also be a starting point for some website copy describing why NaCl/Salt is favorable.

[thoughtpolice]

This is great! Thanks a lot. I think the structure should be:

• The wiki contains the 'field guide' and other points of note.
• Individual modules note their particularly important points and references, etc. Basically every module would probably just have a little bit of the 'field guide' content.

This keeps individual modules straightforward with an online document to deal with the rest. I'll upload a sidebar to the wiki sometime soon so there can be an easily accessible reference across pages (like a field guide, 'why choose salt' guide, libraries page, etc.)

I will also redo the gh-pages branch sometime to be shorter and less verbose, hopefully.

Thanks again for helping!

[tel]

I agree with that. I imagine (per my experience) the workflow for someone trying to use the library would be to see the Hackage documentation first, be directed to the website for some basic motivational examples and an overview of how the library fits together. Here we could also advertise gotchas/concerns/field guide questions and direct people to the Wiki. I think using the Wiki to host something like the field guide is important so that others can add to it should they feel there are more tricks to using this library than we've since highlighted.

In-module documentation is usually most helpful for me when it is comprehensive but also has a very brief guide to what the way you're "supposed" to use the primitives of this module for. I think that's important.

Finally, as I've been looking into the usability of the API a little more I realize there's a definite need for a package architecture which makes it easier to import everything you need. Maybe something like a Crypto.NaCl base package which includes Key and Random and then every "capability" package like PublicKey and OneTimeAuth has both the "internal" side which is just the pure functions for that package and a "quick import" one which also re-exports Crypto.NaCl so that you have import lines like

import Crypto.NaCl import qualified Crypto.NaCl.Encrypt.PublicKey.Core as PK import qualified Crypto.NaCl.Encrypt.Stream.Core as Stream

or

import Crypto.NaCl.Encrypt.PublicKey

which includes all of the functions/constructors/types you need to do public key encryption all in one shot.

… I should probably open a new ticket for this.

On Friday, December 14, 2012 at 6:50 PM, Austin Seipp wrote:

This is great! Thanks a lot. I think the structure should be: The wiki contains the 'field guide' and other points of note.

Individual modules note their particularly important points and references, etc. Basically every module would probably just have a little bit of the 'field guide' content.

This keeps individual modules straightforward with an online document to deal with the rest. I'll upload a sidebar to the wiki sometime soon so there can be an easily accessible reference across pages. I will also redo the gh-pages branch sometime to be shorter and less verbose, hopefully. Thanks again for helping!

— Reply to this email directly or view it on GitHub (https://github.com/thoughtpolice/salt/issues/9#issuecomment-11396701).

[thoughtpolice]

Yes, feel free to create a ticket about the module import structure. It should probably be changed. If there can be non-conflicting names, I'd be happy to just have Crypto.NaCl just import everything.

I've also done a small overhaul on the wiki and given it a sidebar with links to examples. I haven't touched your documentation page, but I made a field guide page you could migrate some of that content to perhaps. Feel free to organize things as you see fit there.

[tel]

Hahah, well, you could always typeclass encrypt/decrypt/hash/sign based off the keys....

I like the sidebarred wiki, nice!