Update docs

README.md

@@ -5,34 +5,11 @@
 BoringSSL bindings for the Rust programming language and TLS adapters for [tokio](https://github.com/tokio-rs/tokio)
 and [hyper](https://github.com/hyperium/hyper) built on top of it.
 
-[Documentation](https://docs.rs/boring).
-
-## Release Support
-
-By default, the crate statically links with the latest BoringSSL master branch.
-
-## Support for pre-built binaries
-
-While this crate can build BoringSSL on its own, you may want to provide pre-built binaries instead.
-To do so, specify the environment variable `BORING_BSSL_PATH` with the path to the binaries.
-
-You can also provide specific headers by setting `BORING_BSSL_INCLUDE_PATH`.
-
-_Notes_: The crate will look for headers in the `$BORING_BSSL_INCLUDE_PATH/openssl/` folder, make sure to place your headers there.
-
-_Warning_: When providing a different version of BoringSSL make sure to use a compatible one, the crate relies on the presence of certain functions.
-
-## Building with a FIPS-validated module
-
-Only BoringCrypto module version 853ca1ea1168dff08011e5d42d94609cc0ca2e27, as certified with
-[FIPS 140-2 certificate 4407](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4407)
-is supported by this crate. Support is enabled by this crate's `fips` feature.
-
-`boring-sys` comes with a test that FIPS is enabled/disabled depending on the feature flag. You can run it as follows:
-
-```bash
-$ cargo test --features fips fips::is_enabled
-```
+## Documentation
+ - Boring API: <https://docs.rs/boring>
+ - tokio TLS adapters: <https://docs.rs/tokio-boring>
+ - hyper HTTPS connector: <https://docs.rs/hyper-boring>
+ - FFI bindings: <https://docs.rs/boring-sys>
 
 ## Contribution
 

boring/src/lib.rs

@@ -1,6 +1,57 @@
 //! Bindings to BoringSSL
 //!
 //! This crate provides a safe interface to the BoringSSL cryptography library.
+//! 
+//! # Versioning
+//! 
+//! ## Crate versioning
+//! 
+//! The crate and all the related crates (FFI bindings, etc.) are released simultaneously and all 
+//! bumped to the same version disregard whether particular crate has any API changes or not. 
+//! However, semantic versioning guarantees still hold, as all the crate versions will be updated
+//! based on the crate with most significant changes. 
+//! 
+//! ## BoringSSL version
+//! 
+//! By default, the crate aims to statically link with the latest BoringSSL master branch.
+//! *Note*: any BoringSSL revision bumps will be released as a major version update of all crates. 
+//! 
+//! # Compilation and linking options
+//! 
+//! ## Support for pre-built binaries
+//! 
+//! While this crate can build BoringSSL on its own, you may want to provide pre-built binaries instead.
+//! To do so, specify the environment variable `BORING_BSSL_PATH` with the path to the binaries.
+//! 
+//! You can also provide specific headers by setting `BORING_BSSL_INCLUDE_PATH`.
+//! 
+//! _Notes_: The crate will look for headers in the `$BORING_BSSL_INCLUDE_PATH/openssl/` folder, make sure to place your headers there.
+//! 
+//! _Warning_: When providing a different version of BoringSSL make sure to use a compatible one, the crate relies on the presence of certain functions.
+//! 
+//! ## Building with a FIPS-validated module
+//! 
+//! Only BoringCrypto module version `853ca1ea1168dff08011e5d42d94609cc0ca2e27`, as certified with
+//! [FIPS 140-2 certificate 4407](https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4407)
+//! is supported by this crate. Support is enabled by this crate's `fips` feature.
+//! 
+//! `boring-sys` comes with a test that FIPS is enabled/disabled depending on the feature flag. You can run it as follows:
+//! 
+//! ```bash
+//! $ cargo test --features fips fips::is_enabled
+//! ```
+//! 
+//! # Optional patches
+//! 
+//! ## Raw Public Key
+//! 
+//! The crate can be compiled with [RawPublicKey](https://datatracker.ietf.org/doc/html/rfc7250)
+//! support by turning on `rpk` compilation feature.
+//! 
+//! ## Post-quantum cryptography
+//! 
+//! The crate can be compiled with [post-quantum cryptography](https://blog.cloudflare.com/post-quantum-for-all/)
+//! support by turning on `post-quantum` compilation feature.
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]