|
1 | | -# Python code style |
| 1 | +# Mechanical Source Issues¶ |
| 2 | + |
| 3 | +## Source Code Formatting¶ |
| 4 | + |
| 5 | +### Python code style |
2 | 6 |
|
3 | | -## black |
4 | 7 |
|
5 | 8 | We use [black](https://black.readthedocs.io/en/stable/) code formatter. |
6 | 9 |
|
7 | 10 | - Revision: `20.8b1` or branch `stable`. |
8 | 11 | - See configuration in `pyproject.toml`. |
9 | 12 |
|
10 | 13 | Run before each commit: `black .` |
| 14 | + |
| 15 | +### C/C++ File Headers |
| 16 | + |
| 17 | +Every C API source file should have a header on it that describes the basic |
| 18 | +purpose of the file. The standard header looks like this: |
| 19 | + |
| 20 | +``` |
| 21 | +//===----- dpctl_sycl_event_interface.h - C API for sycl::event -*-C++-*- ===// |
| 22 | +// |
| 23 | +// Data Parallel Control (dpCtl) |
| 24 | +// |
| 25 | +// Copyright 2020-2021 Intel Corporation |
| 26 | +// |
| 27 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 28 | +// you may not use this file except in compliance with the License. |
| 29 | +// You may obtain a copy of the License at |
| 30 | +// |
| 31 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 32 | +// |
| 33 | +// Unless required by applicable law or agreed to in writing, software |
| 34 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 35 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 36 | +// See the License for the specific language governing permissions and |
| 37 | +// limitations under the License. |
| 38 | +// |
| 39 | +//===----------------------------------------------------------------------===// |
| 40 | +/// |
| 41 | +/// \file |
| 42 | +/// This header declares a C API to a sub-set of the sycl::event interface. |
| 43 | +/// |
| 44 | +//===----------------------------------------------------------------------===// |
| 45 | +``` |
| 46 | +Few things to note about this format: |
| 47 | +- The `-*- C++ -*-` string on the first line is needed to tell Emacs that |
| 48 | + the file is a C++ file. The string is only needed for `*.h` headers and |
| 49 | + should be omitted for `*.cpp` files. Without the string Emacs assumes that |
| 50 | + file is a C header. |
| 51 | +- The copyright year should be updated every calendar year. |
| 52 | +- Each comment line should be a max of 80 chars. |
| 53 | +- A Doxygen `\file` tag describing the contents of the file must be provided. |
| 54 | + Also note that the `\file` tag is inside a Doxygen comment block (defined by `///` |
| 55 | + comment marker instead of the `//` comment marker used in the rest of the header. |
| 56 | + |
| 57 | +### Python File Headers |
| 58 | + |
| 59 | +Every Python and Cython file should only include the following license header: |
| 60 | + |
| 61 | +``` |
| 62 | +# Data Parallel Control (dpCtl) |
| 63 | +# |
| 64 | +# Copyright 2020-2021 Intel Corporation |
| 65 | +# |
| 66 | +# Licensed under the Apache License, Version 2.0 (the "License"); |
| 67 | +# you may not use this file except in compliance with the License. |
| 68 | +# You may obtain a copy of the License at |
| 69 | +# |
| 70 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 71 | +# |
| 72 | +# Unless required by applicable law or agreed to in writing, software |
| 73 | +# distributed under the License is distributed on an "AS IS" BASIS, |
| 74 | +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 75 | +# See the License for the specific language governing permissions and |
| 76 | +# limitations under the License. |
| 77 | +``` |
| 78 | +The copyright year should be updated every calendar year. |
0 commit comments