Update style guide to change |...| to `...` for code in comments Code in comments should now be enclosed in `backticks`, not |pipes|. Bug: 42290410 Change-Id: I97c0b0fe158343fef1e1b60336e1d84f6a6a6964 Reviewed-on: https://boringssl-review.googlesource.com/c/boringssl/+/96187 Auto-Submit: Lily Chen <chlily@google.com> Presubmit-BoringSSL-Verified: boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com <boringssl-scoped@luci-project-accounts.iam.gserviceaccount.com> Commit-Queue: David Benjamin <davidben@google.com> Reviewed-by: David Benjamin <davidben@google.com>
diff --git a/API-CONVENTIONS.md b/API-CONVENTIONS.md index 5202968..14a08ea 100644 --- a/API-CONVENTIONS.md +++ b/API-CONVENTIONS.md
@@ -205,7 +205,7 @@ EVP_DigestUpdate(&ctx, "hello ", 6) && EVP_DigestUpdate(&ctx, "world", 5) && EVP_DigestFinal_ex(&ctx, md, &md_len); - EVP_MD_CTX_cleanup(&ctx); /* Release |ctx|. */ + EVP_MD_CTX_cleanup(&ctx); /* Release `ctx`. */ Note that `EVP_MD_CTX_cleanup` is called whether or not the `EVP_Digest*` operations succeeded. More complex C functions may use the `goto err` pattern:
diff --git a/STYLE.md b/STYLE.md index 7ae6981..b1430a3 100644 --- a/STYLE.md +++ b/STYLE.md
@@ -215,8 +215,8 @@ For example, - /* CBB_add_asn sets |*out_contents| to a |CBB| into which the contents of an - * ASN.1 object can be written. The |tag| argument will be used as the tag for + /* CBB_add_asn sets `*out_contents` to a `CBB` into which the contents of an + * ASN.1 object can be written. The `tag` argument will be used as the tag for * the object. It returns one on success or zero on error. */ OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, unsigned tag); @@ -227,15 +227,15 @@ file. The style is based on that of Go. The first sentence begins with the symbol name, optionally prefixed with "A" or "An". Apart from the initial mention of symbol, references to other symbols or parameter -names should be surrounded by |pipes|. +names should be surrounded by `` `backticks` ``. Documentation should be concise but completely describe the exposed behavior of the function. Pay special note to success/failure behaviors and caller obligations on object lifetimes. If this sacrifices conciseness, consider simplifying the function's behavior. - // EVP_DigestVerifyUpdate appends |len| bytes from |data| to the data which - // will be verified by |EVP_DigestVerifyFinal|. It returns one on success and + // EVP_DigestVerifyUpdate appends `len` bytes from `data` to the data which + // will be verified by `EVP_DigestVerifyFinal`. It returns one on success and // zero otherwise. OPENSSL_EXPORT int EVP_DigestVerifyUpdate(EVP_MD_CTX *ctx, const void *data, size_t len); @@ -243,14 +243,14 @@ Explicitly mention any surprising edge cases or deviations from common return value patterns in legacy functions. - // RSA_private_encrypt encrypts |flen| bytes from |from| with the private key in - // |rsa| and writes the encrypted data to |to|. The |to| buffer must have at - // least |RSA_size| bytes of space. It returns the number of bytes written, or - // -1 on error. The |padding| argument must be one of the |RSA_*_PADDING| - // values. If in doubt, |RSA_PKCS1_PADDING| is the most common. + // RSA_private_encrypt encrypts `flen` bytes from `from` with the private key in + // `rsa` and writes the encrypted data to `to`. The `to` buffer must have at + // least `RSA_size` bytes of space. It returns the number of bytes written, or + // -1 on error. The `padding` argument must be one of the `RSA_*_PADDING` + // values. If in doubt, `RSA_PKCS1_PADDING` is the most common. // // WARNING: this function is dangerous because it breaks the usual return value - // convention. Use |RSA_sign_raw| instead. + // convention. Use `RSA_sign_raw` instead. OPENSSL_EXPORT int RSA_private_encrypt(int flen, const uint8_t *from, uint8_t *to, RSA *rsa, int padding);