AWS-LC followings the #BoringSSL-Style-Guide conventions unless specified otherwise here.
This section provides a brief overview of how to use Doxygen as well as the standard conventions we follow in our code.
All public headers (files in the include directory generally) must have the appropriate documentation. Besides documentation on the exported symbols, the file should have at least a brief description of its purpose.
/**
* @file
* @brief A short description.
*
* @details
* A longer, optional description of the file's purpose.
*/In general, @file should not include the (optional name parameter)[https://www.doxygen.nl/manual/commands.html#cmdfile].
When a function is added to a public header or an existing function is modified, the documentation for the function must included. This is to include a description of the function if one doesn't already exist. Documentation should be ordered as follows:
/**
* @brief One-line description
*
* @details
* More info.
* Across multiple lines or paragraphs.
*
* @param dir param_1 Description
* @param dir param_2 Description
*
* @return Description
* or
* @retval val1 Description
* @retval val2 Description
*/Warnings, todos, and deprecated commands can be in any order but should be at the end of the standard block above.
@param tags for each parameter, including direction (in/out/in,out)
will be added. Parameters should be in the same order as the function declaration.
/**
* Copies a block of data into a buffer.
* @param[in] x Integer between 1 and 10
* @param[in,out] y If x is odd, add to *y
* @param[out] z Stores x cubed
*/
int weird_compute(int x, int *y, int *z);@returns or @retval
should be used.
/**
* @return The number of bytes written to the buffer.
*/or
/**
* @retval -1 Error
* @retval 0 Success
*/When a symbol is added to a public header or an existing one is modified, the documentation must be included and/or updated.
Use the double asterisk C-style Doxygen blocks (/** */) instead of C++ lines (///) or comment block formats. The starting symbol /** and closing symbol */ should be on their own lines:
/**
* ... Documentation ...
*/except when closing a member group:
/** @} Member Group Name */struct buf_mem_st {
/** current number of bytes */
size_t length;
/** data buffer */
char *data;
/** size of buffer */
size_t max;
};should be used, not:
struct buf_mem_st {
size_t length; /** current number of bytes */
char *data; /** data buffer */
size_t max; /** size of buffer */
};Use @ to prefix all commands instead of \.
Instead of relying on Doxygen to generate a brief description, explicitly use the @brief command. For readability, this should end with a period and if there's further documentation, an empty line should follow the command in the block.
/**
* @brief A short description.
*/
/**
* @brief A short description followed by details.
*
* ... More documentation ...
*/Instead of relying on Doxygen to decide what is the details section, the @details command should be used. The command should be on its own line.
/**
* @details
* ... Detailed information...
*/When including code inline, to get typewriter font, use backticks instead of the @c command. This should also be used when referncing the symbols being documented.
/**
* @details
* `this_function` encodes...
*/
int this_function()If your documentation includes full lines of code (such as examples), surround the line(s) by @code/@endcode for syntax highlighting and automatic generation of links to documentation for the symbols used. For readability, empty lines should surround the block and the commands should be on their own lines.
/**
* @details
* ... Documentation ...
*
* @code{.c}
* uint8_t dst = allocate(max_len);
* size_t len = encode_bytes(dst, src, src_len);
* @endcode
*/When a group of functions in a header file are related, use grouping.
Use the group type that makes the most sense but avoid the use of @defgroup.
Use grouping or the @copydoc to avoid duplication.
Add the @deprecated tag to all code that is marked as
deprecated. Adding a description is optional.
Note: The @copy... commands don't work correctly in the index of deprecated functions, so text may need to be copied.
Before each struct, use the `@struct command for proper documentation linking.
Typedefs require special handling for correct format linking in our code base. Use the following block
before each typedef to avoid recursion errors and allow users to navigate the documentation easily:
/**
* @typedef EVP_ENCODE_CTX
* @copydoc evp_encode_ctx_st
* @see evp_encode_ctx_st
*/
typedef struct evp_encode_ctx_st EVP_ENCODE_CTX;This command changes just changes how text is displayed. If the block includes a warning, include that text
inside a @warning command.
Use of the @todo command allows for list generation
as needed.
In some cases, Doxygen may not be able to automatically link to symbols. Explicit links may be needed: https://www.doxygen.nl/manual/autolink.html.
When documentation should be in italics, use the Markdown underscore syntax.
Roman text _italic text_ Roman text
When documentation should be in bold, use the Markdown double asterisk syntax.
Roman text **bold text** Roman text
For unordered lists, use * for each item, not - or +. For orded lists, use 1. for each item. Do not use other numbers, allow them to be generated automatically. Nested lists should be indented by two spaces.
1. First enumerated point (level 1)
1. Second enuemrated point (level 1)
* First unordered point (level 2)
* Second unordered point (level 2)
1. Third enumerated point (level 1)
When lines, such as command line examples, are included use the @verbatim
command.
If tables are needed, Markdown Tables should be used.
NULLshould be used to refer to the null value- Integer values should be written in (-1 not "negative one" or "negative 1")
BoringSSL usually follows the Google C++ style guide, The rest of this document describes differences and clarifications on top of the base guide.
As a derivative of OpenSSL, BoringSSL contains a lot of legacy code that does not follow this style guide. Particularly where public API is concerned, balance consistency within a module with the benefits of a given rule. Module-wide deviations on naming should be respected while integer and return value conventions take precedence over consistency.
Modules from OpenSSL's legacy ASN.1 and X.509 stack are retained for
compatibility and left largely unmodified. To ease importing patches from
upstream, they match OpenSSL's new indentation style. For Emacs,
doc/openssl-c-indent.el from OpenSSL may be helpful in this.
The majority of the project is in C, so C++-specific rules in the Google style guide do not apply. Support for C99 features depends on our target platforms. Typically, Chromium's target MSVC is the most restrictive.
Variable declarations in the middle of a function or inside a for loop are
allowed and preferred where possible. Note that the common goto err cleanup
pattern requires lifting some variable declarations.
Comments should be // C99-style for consistency with C++.
When declaring pointer types, * should be placed next to the variable name,
not the type. So
uint8_t *ptr;
not
uint8_t* ptr;
Rather than malloc() and free(), use the wrappers OPENSSL_malloc()
and OPENSSL_free(). Use the standard C assert() function freely.
Use the following wrappers, found in crypto/internal.h instead of the
corresponding C standard library functions. They behave the same but avoid
confusing undefined behavior.
OPENSSL_memchrOPENSSL_memcmpOPENSSL_memcpyOPENSSL_memmoveOPENSSL_memset
For new constants, prefer enums when the values are sequential and typed
constants for flags. If adding values to an existing set of #defines,
continue with #define.
libssl was originally written in C but is being incrementally rewritten in
C++11. As of writing, much of the style matches our C conventions rather than
Google C++. Additionally, libssl on Linux currently may not depend on the C++
runtime. See the C++ utilities in ssl/internal.h for replacements for
problematic C++ constructs. The util/check_imported_libraries.go script may be
used with a shared library build to check if a new construct is okay.
If unsure, match surrounding code. Discrepancies between it and Google C++ style will be fixed over time.
Single-statement blocks are not allowed. All conditions and loops must use braces:
if (foo) {
do_something();
}
not
if (foo)
do_something();
Prefer using explicitly-sized integers where appropriate rather than
generic C ones. For instance, to represent a byte, use uint8_t, not
unsigned char. Likewise, represent a two-byte field as uint16_t, not
unsigned short.
Sizes are represented as size_t.
Within a struct that is retained across the lifetime of an SSL
connection, if bounds of a size are known and it's easy, use a smaller
integer type like uint8_t. This is a "free" connection footprint
optimization for servers. Don't make code significantly more complex for
it, and do still check the bounds when passing in and out of the
struct. This narrowing should not propagate to local variables and
function parameters.
When doing arithmetic, account for overflow conditions.
Except with platform APIs, do not use ssize_t. MSVC lacks it, and
prefer out-of-band error signaling for size_t (see Return values).
Follow Google naming conventions in C++ files. In C files, use the following naming conventions for consistency with existing OpenSSL and C styles:
Define structs with typedef named TYPE_NAME. The corresponding struct
should be named struct type_name_st.
Name public functions as MODULE_function_name, unless the module
already uses a different naming scheme for legacy reasons. The module
name should be a type name if the function is a method of a particular
type.
Some types are allocated within the library while others are initialized
into a struct allocated by the caller, often on the stack. Name these
functions TYPE_NAME_new/TYPE_NAME_free and
TYPE_NAME_init/TYPE_NAME_cleanup, respectively. All TYPE_NAME_free
functions must do nothing on NULL input.
If a variable is the length of a pointer value, it has the suffix
_len. An output parameter is named out or has an out_ prefix. For
instance, For instance:
uint8_t *out,
size_t *out_len,
const uint8_t *in,
size_t in_len,
Name public headers like include/openssl/evp.h with header guards like
OPENSSL_HEADER_EVP_H. Name internal headers like
crypto/ec/internal.h with header guards like
OPENSSL_HEADER_EC_INTERNAL_H.
Name enums like enum unix_hacker_t. For instance:
enum should_free_handshake_buffer_t {
free_handshake_buffer,
dont_free_handshake_buffer,
};
As even malloc may fail in BoringSSL, the vast majority of functions
will have a failure case. Functions should return int with one on
success and zero on error. Do not overload the return value to both
signal success/failure and output an integer. For example:
OPENSSL_EXPORT int CBS_get_u16(CBS *cbs, uint16_t *out);
If a function needs more than a true/false result code, define an enum rather than arbitrarily assigning meaning to int values.
If a function outputs a pointer to an object on success and there are no
other outputs, return the pointer directly and NULL on error.
Where not constrained by legacy code, parameter order should be:
- context parameters
- output parameters
- input parameters
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
* the object. It returns one on success or zero on error. */
OPENSSL_EXPORT int CBB_add_asn1(CBB *cbb, CBB *out_contents, unsigned tag);
BoringSSL is used by many projects with many different build tools.
Reimplementing and maintaining build logic in each downstream build is
cumbersome, so build logic should be avoided where possible. Platform-specific
files should be excluded by wrapping the contents in #ifdefs, rather than
computing platform-specific file lists. Generated source files such as perlasm
and err_data.c may be used in the standalone CMake build but, for downstream
builds, they should be pre-generated in generate_build_files.py.