docs: clarify cmd_psuh signature and explain UNUSED macro
The sample program, as written, would no longer build for at least two reasons: - Since this document was first written, the convention to call a subcommand implementation has changed, and cmd_psuh() now needs to accept the fourth parameter, repository. - These days, compiler warning options for developers include one that detects and complains about unused parameters, so ones that are deliberately unused have to be marked as such. Update the old-style examples to adjust to the current practices, with explanations as needed. Signed-off-by: K Jayatheerth <jayatheerthkulkarni2005@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
K Jayatheerth committed
May 18, 2025 at 13:13 UTC
a1dcf6b2897e34b684249e6a823221a063ae3910
1 file changed
+23
-5
Documentation/MyFirstContribution.adoc
+23
-5
@@ -142,15 +142,31 @@ command in `builtin/psuh.c`. Create that file, and within it, write the entry
142
point for your command in a function matching the style and signature:
143
144
----
145
-int cmd_psuh(int argc, const char **argv, const char *prefix)
145
+int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
146
+ const char *prefix UNUSED, struct repository *repo UNUSED)
147
----
148
149
+A few things to note:
150
+
151
+* A subcommand implementation takes its command line arguments
152
+ in `int argc` + `const char **argv`, like `main()` would.
153
+
154
+* It also takes two extra parameters, `prefix` and `repo`. What
155
+ they mean will not be discussed until much later.
156
+
157
+* Because this first example will not use any of the parameters,
158
+ your compiler will give warnings on unused parameters. As the
159
+ list of these four parameters is mandated by the API to add
160
+ new built-in commands, you cannot omit them. Instead, you add
161
+ `UNUSED` to each of them to tell the compiler that you *know*
162
+ you are not (yet) using it.
163
+
164
We'll also need to add the declaration of psuh; open up `builtin.h`, find the
165
declaration for `cmd_pull`, and add a new line for `psuh` immediately before it,
166
in order to keep the declarations alphabetically sorted:
167
168
----
153
-int cmd_psuh(int argc, const char **argv, const char *prefix);
169
+int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);
170
----
171
172
Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to
@@ -166,7 +182,8 @@ Throughout the tutorial, we will mark strings for translation as necessary; you
182
should also do so when writing your user-facing commands in the future.
183
184
----
169
-int cmd_psuh(int argc, const char **argv, const char *prefix)
185
+int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
186
+ const char *prefix UNUSED, struct repository *repo UNUSED)
187
{
188
printf(_("Pony saying hello goes here.\n"));
189
return 0;
@@ -279,8 +296,9 @@ on the reference implementation linked at the top of this document.
296
It's probably useful to do at least something besides printing out a string.
297
Let's start by having a look at everything we get.
298
282
-Modify your `cmd_psuh` implementation to dump the args you're passed, keeping
283
-existing `printf()` calls in place:
299
+Modify your `cmd_psuh` implementation to dump the args you're passed,
300
+keeping existing `printf()` calls in place; because the args are now
301
+used, remove the `UNUSED` macro from them:
302
303
----
304
int i;