Description
Microsoft SAL annotations, which were present before clang itself and is heavily used in Windows kernel drivers, are not well supported by clang-format.
In particular, clang-format seems to treat function SAL annotations as new function declarations or function calls.
Also, it seems clang-format has a strong bias toward packing as much as possible in a single line, regardless of the options set.
This implicit and forced packing is not universally helpful, because at least with kernel drivers, the strong preference is be explicit one line at a time when reading or controlling code execution.
For example, the following is a common pattern found in Windows. These patterns were present since 1990's with the NT OS/2 coding conventions and later enhanced with SAL.
Goal:
NTSTATUS
GetPropertyValue(
_In_ HANDLE Handle,
_Out_ PUNICODE_STRING Value
);
clang-format, regardless of options (including AlignAfterOpenBracket: Align), will pack this into a single line.
Reformatted:
NTSTATUS
GetPropertyValue(_In_ HANDLE Handle, _Out_ PUNICODE_STRING Value);
Here is another example with function SAL annotations. clang-format will also incorrectly pack the SAL annotations and return type into a single line, or sometimes break and indent for unknown reasons.
Goal:
_Must_inspect_result_
_Success_(return == 0)
unsigned int
GetPropertyValue(
_In_ HANDLE Handle,
_Out_ PUNICODE_STRING Value
);
Reformatted:
_Must_inspect_result_ _Success_(return == 0) unsigned int
GetPropertyValue(_In_ HANDLE Handle, _Out_ PUNICODE_STRING Value);
Please make clang-format honor the option to always break function parameters in both function declarations and implementations.
Also provide a way for clang-format to at least ignore function SAL annotations that are declared before the return type, or honor to always break all decorations (including the return type) before the function name.