Skip to content

Commit

Permalink
Line-wrap CONTRIBUTING.md to 99 columns
Browse files Browse the repository at this point in the history
  • Loading branch information
Susurrus committed Jun 3, 2017
1 parent 5fe187d commit 4c58c31
Showing 1 changed file with 25 additions and 11 deletions.
36 changes: 25 additions & 11 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
# Guidelines

* Never get definitions from MinGW headers or MSDN. Always stick to the Windows SDK headers, in particular the latest Windows 10 SDK.
* Definitions which depend on whether `UNICODE` is defined should not be included. It is the user's responsibility to explicitly choose between `W` and `A` functions (and they should always choose `W`).
* Never get definitions from MinGW headers or MSDN. Always stick to the Windows SDK headers, in
particular the latest Windows 10 SDK.
* Definitions which depend on whether `UNICODE` is defined should not be included. It is the
user's responsibility to explicitly choose between `W` and `A` functions (and they should always
choose `W`).

## Newlines and indentation

* The maximum line length for `winapi-rs` is 99, and is strictly enforced.
* Avoid line breaks when possible, but if you cannot make it fit, add line breaks as late as possible.
* Avoid line breaks when possible, but if you cannot make it fit, add line breaks as late as
possible.
* When breaking on binary operators, put the operator at the beginning of the new line.
* Do not use aligned indentation. Indentation should always be block indentation.
* Always use spaces for indentation.
Expand All @@ -31,7 +35,8 @@ use um::d3dcommon::{

## Extern functions

* The calling convention specified should be the one for 32bit. Specify `system` for stdcall and `C` for cdecl (and `fastcall` for those couple of fastcall functions out there).
* The calling convention specified should be the one for 32bit. Specify `system` for stdcall and
`C` for cdecl (and `fastcall` for those couple of fastcall functions out there).
* One parameter per line.

```Rust
Expand Down Expand Up @@ -117,7 +122,8 @@ pub type PGROUP_AFFINITY = *mut GROUP_AFFINITY;

## Unions

* `UNION!` is being deprecated in favor of `UNION2!` in order to more closely align with the new untagged union feature.
* `UNION!` is being deprecated in favor of `UNION2!` in order to more closely align with the new
untagged union feature.

```C
typedef union {
Expand All @@ -140,8 +146,11 @@ pub type PUSN_RECORD_UNION = *mut USN_RECORD_UNION;

## Anonymous unions and structs

* If the type `FOO` contains a single anonymous struct or union, give the anonymous struct or union a name of `FOO_s` or `FOO_u` respectively, and the field a name of `s` or `u` respectively.
* If the type `FOO` contains multiple anonymous structs or unions, append a number, such as `s1: FOO_s1` `s2: FOO_s2` or `u1: FOO_u1` `u2: FOO_u2`.
* If the type `FOO` contains a single anonymous struct or union, give the anonymous struct or
union a name of `FOO_s` or `FOO_u` respectively, and the field a name of `s` or `u`
respectively.
* If the type `FOO` contains multiple anonymous structs or unions, append a number, such as:
`s1: FOO_s1`/`s2: FOO_s2` or `u1: FOO_u1`/`u2: FOO_u2`.

## COM interfaces

Expand Down Expand Up @@ -173,11 +182,16 @@ For COM interfaces without a UUID, a UUID of all-zeroes should be used.
* All definitions go into the source file that directly maps to the header the definition is from.
* Stuff in `src/winrt` is special and has its own namespaced organization.
* Definitions are defined in the same order as they are in the original header.
* The `lib` folder is legacy from 0.2 and will eventually disappear once all definitions have been moved to their correct locations.
* The `lib` folder is legacy from 0.2 and will eventually disappear once all definitions have been
moved to their correct locations.

## Dealing with duplicates

* Sometimes two headers will define the same thing.
* If the duplicated thing is a simple typedef or function definition or constant, then duplicate the definition.
* If the duplicated thing is a struct or COM interface or union, then choose one header to be the canonical source of truth for that definition and publicly re-export the thing from the other header.
* Sometimes a COM interface will have two methods with identical names. If the two methods are both named `Foo`, then name them `Foo1` and `Foo2`.
* If the duplicated thing is a simple typedef or function definition or constant, then
duplicate the definition.
* If the duplicated thing is a struct or COM interface or union, then choose one header to be
the canonical source of truth for that definition and publicly re-export the thing from the
other header.
* Sometimes a COM interface will have two methods with identical names. If the two methods are
both named `Foo`, then name them `Foo1` and `Foo2`.

0 comments on commit 4c58c31

Please sign in to comment.