Drake
unused.h
Go to the documentation of this file.
1 #pragma once
2 
3 namespace drake {
4 
5 /// Documents the argument(s) as unused, placating GCC's -Wunused-parameter
6 /// warning. This can be called within function bodies to mark that certain
7 /// parameters are unused.
8 ///
9 /// When possible, removing the unused parameter is better than placating the
10 /// warning. However, in some cases the parameter is part of a virtual API or
11 /// template concept that is used elsewhere, so we can't remove it. In those
12 /// cases, this function might be an appropriate work-around.
13 ///
14 /// Here's rough advice on how to fix Wunused-parameter warnings:
15 ///
16 /// (1) If the parameter can be removed entirely, prefer that as the first
17 /// choice. (This may not be possible if, e.g., a method must match some
18 /// virtual API or template concept.)
19 ///
20 /// (2) Unless the parameter name has acute value, prefer to omit the name of
21 /// the parameter, leaving only the type, e.g.
22 /// @code
23 /// void Print(const State& state) override { /* No state to print. */ }
24 /// @endcode
25 /// changes to
26 /// @code
27 /// void Print(const State&) override { /* No state to print. */}
28 /// @endcode
29 /// This no longer triggers the warning and further makes it clear that a
30 /// parameter required by the API is definitively unused in the function.
31 ///
32 /// This is an especially good solution in the context of method
33 /// definitions (vs declarations); the parameter name used in a definition
34 /// is entirely irrelevant to Doxygen and most readers.
35 ///
36 /// (3) When leaving the parameter name intact has acute value, it is
37 /// acceptable to keep the name and mark it `unused`. For example, when
38 /// the name appears as part of a virtual method's base class declaration,
39 /// the name is used by Doxygen to document the method, e.g.,
40 /// @code
41 /// /** Sets the default State of a System. This default implementation is to
42 /// set all zeros. Subclasses may override to use non-zero defaults. The
43 /// custom defaults may be based on the given @p context, when relevant. */
44 /// virtual void SetDefault(const Context<T>& context, State<T>* state) const {
45 /// unused(context);
46 /// state->SetZero();
47 /// }
48 /// @endcode
49 ///
50 template <typename ... Args>
51 void unused(const Args& ...) {}
52 
53 } // namespace drake
Definition: automotive_demo.cc:88
void unused(const Args &...)
Documents the argument(s) as unused, placating GCC&#39;s -Wunused-parameter warning.
Definition: unused.h:51