kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

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>
maint
K Jayatheerth 2025-05-18 13:13:16 +05:30 committed by Junio C Hamano
parent 3749b8a795
commit a1dcf6b289
1 changed files with 23 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
Documentation/MyFirstContribution.adoc
View File

@ -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;