[PATCH v4 2/3] 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 calling convention
to subcommand implementation has changed, and now cmd_psuh()
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>
---
Documentation/MyFirstContribution.adoc | 28 +++++++++++++++++++++-----
1 file changed, 23 insertions(+), 5 deletions(-)
Show changes to Documentation/MyFirstContribution.adoc +23 −5
diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
index ef190d8748..da15d43d1f 100644
--- a/Documentation/MyFirstContribution.adoc
+++ b/Documentation/MyFirstContribution.adoc
@@ -142,15 +142,31 @@ command in `builtin/psuh.c`. Create that file, and within it, write the entry
point for your command in a function matching the style and signature:
----
-int cmd_psuh(int argc, const char **argv, const char *prefix)
+int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
+ const char *prefix UNUSED, struct repository *repo UNUSED)
----
+A few things to note:
+
+* A subcommand implementation takes its command line arguments
+ in `int argc` + `const char **argv`, like `main()` would.
+
+* It also takes two extra parameters, `prefix` and `repo`. What
+ they mean will not be discussed until much later.
+
+* Because this first example will not use any of the parameters,
+ your compiler will give warnings on unused parameters. As the
+ list of these four parameters is mandated by the API to add
+ new built-in commands, you cannot omit them. Instead, you add
+ `UNUSED` to each of them to tell the compiler that you *know*
+ you are not (yet) using it.
+
We'll also need to add the declaration of psuh; open up `builtin.h`, find the
declaration for `cmd_pull`, and add a new line for `psuh` immediately before it,
in order to keep the declarations alphabetically sorted:
----
-int cmd_psuh(int argc, const char **argv, const char *prefix);
+int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);
----
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
should also do so when writing your user-facing commands in the future.
----
-int cmd_psuh(int argc, const char **argv, const char *prefix)
+int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
+ const char *prefix UNUSED, struct repository *repo UNUSED)
{
printf(_("Pony saying hello goes here.\n"));
return 0;
@@ -279,8 +296,9 @@ on the reference implementation linked at the top of this document.
It's probably useful to do at least something besides printing out a string.
Let's start by having a look at everything we get.
-Modify your `cmd_psuh` implementation to dump the args you're passed, keeping
-existing `printf()` calls in place:
+Modify your `cmd_psuh` implementation to dump the args you're passed,
+keeping existing `printf()` calls in place; because the args are now
+used, remove the `UNUSED` macro from them:
----
int i;
--
2.49.GIT
K Jayatheerth