From 15cf6b995624e938209e611f3953dd8dbb7a57b8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 21 Dec 2013 19:22:39 -0800 Subject: A handful of cleanups and rewordings to the docs --- docs/contributing.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index cb9c7283..f176393f 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -53,11 +53,10 @@ API Considerations Most projects' APIs are designed with a philosophy of "make easy things easy, and make hard things possible". One of the perils of writing cryptographic code -is that code that is secure looks just like code that isn't, and produces -results that are also difficult to distinguish. As a result ``cryptography`` -has, as a design philosophy: "make it hard to do insecure things". Here are a -few strategies for API design which should be both followed, and should inspire -other API choices: +is that secure code looks just like insecure code, and it's results are almost +always indistinguishable. As a result ``cryptography`` has, as a design +philosophy: "make it hard to do insecure things". Here are a few strategies for +API design which should be both followed, and should inspire other API choices: If it is incorrect to ignore the result of a method, it should raise an exception, and not return a boolean ``True``/``False`` flag. For example, a @@ -163,7 +162,7 @@ as much as possible. To that end: * When documenting a generic interface, use a strong algorithm in examples. (e.g. when showing a hashing example, don't use - :class:`cryptography.hazmat.primitives.hashes.MD5`) + :class:`~cryptography.hazmat.primitives.hashes.MD5`) * When giving prescriptive advice, always provide references and supporting material. * When there is real disagreement between cryptographic experts, represent both @@ -206,7 +205,7 @@ automatically, so all you have to do is: $ py.test ... - 4294 passed in 15.24 seconds + 62746 passed in 220.43 seconds This runs the tests with the default Python interpreter. @@ -244,7 +243,8 @@ Use `tox`_ to build the documentation. For example: docs: commands succeeded congratulations :) -The HTML documentation index can now be found at ``docs/_build/html/index.html`` +The HTML documentation index can now be found at +``docs/_build/html/index.html``. .. _`GitHub`: https://github.com/pyca/cryptography -- cgit v1.2.3 From 95243f5b34f6cdfc16fb95669efbe2a61ac81179 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 21 Dec 2013 19:37:24 -0800 Subject: English, how does it work? --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index f176393f..b1702df8 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -53,7 +53,7 @@ API Considerations Most projects' APIs are designed with a philosophy of "make easy things easy, and make hard things possible". One of the perils of writing cryptographic code -is that secure code looks just like insecure code, and it's results are almost +is that secure code looks just like insecure code, and its results are almost always indistinguishable. As a result ``cryptography`` has, as a design philosophy: "make it hard to do insecure things". Here are a few strategies for API design which should be both followed, and should inspire other API choices: -- cgit v1.2.3