Skip to content

Commit 6a7d2a7

Browse files
authored
Add more guidelines to contributing doc (#196)
1 parent fe7ca50 commit 6a7d2a7

File tree

1 file changed

+10
-2
lines changed

1 file changed

+10
-2
lines changed

docs/CONTRIBUTING.md

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,19 @@ Prefer using `quickcheck` tests and doctests where they make sense.
4848

4949
Avoid writing tests that simply restate the definition of a function. E.g. for `fn square(x: i32) { x*x }` do not write a test that asserts `square(3) == 3*3`.
5050

51-
### Wrapping `rcl` functions
51+
### Return type to use when wrapping `rcl` functions
5252
Functions from `rcl` can typically return error codes. This does not necessarily mean that the `rclrs` function using it must return `Result`. If the error conditions can be determined, from reading `rcl` comments and source code, to never occur, the return code doesn't need to be propagated but only `debug_assert!`ed to be ok. This assert guards against `rcl` introducing a new error condition in the future.
5353

5454
An example would be a function that only returns an error when the pointer we pass in is null or points to an uninitialized object. If we obtain the pointer from a reference, it can't be null, and if the object that is referenced is guaranteed to be initialized, there is no need to return a `Result`.
5555

56+
### References vs raw pointers
57+
58+
Do not cast references to raw pointers where it's not needed. Since references coerce to raw pointers, they can be directly used as arguments to C functions in most cases.
59+
60+
### Implementing the `Drop` trait
61+
62+
Generally, a `rcl` type should have a `Drop` impl that calls its `fini()` function. However, there are some cases where this is not possible, e.g. when the type is part of another `rcl` type that owns and finalizes it, or when the `fini()` function takes extra arguments. In these cases, it needs to be decided individually if and where to call `fini()`, and care must be taken to not return early from a function with `?` before the relevant `fini()` functions have been called.
63+
5664
## License
5765
Any contribution that you make to this repository will
5866
be under the Apache 2 License, as dictated by that
@@ -66,4 +74,4 @@ be under the Apache 2 License, as dictated by that
6674
Notwithstanding the above, nothing herein shall supersede or modify
6775
the terms of any separate license agreement you may have executed
6876
with Licensor regarding such Contributions.
69-
~~~
77+
~~~

0 commit comments

Comments
 (0)