From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.polymtl.ca (smtp.polymtl.ca [132.207.4.11]) by sourceware.org (Postfix) with ESMTPS id 7A8133860C3B for ; Mon, 8 Mar 2021 22:52:25 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 7A8133860C3B Received: from simark.ca (simark.ca [158.69.221.121]) (authenticated bits=0) by smtp.polymtl.ca (8.14.7/8.14.7) with ESMTP id 128MqJhI030747 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 8 Mar 2021 17:52:24 -0500 DKIM-Filter: OpenDKIM Filter v2.11.0 smtp.polymtl.ca 128MqJhI030747 Received: from [10.0.0.11] (192-222-157-6.qc.cable.ebox.net [192.222.157.6]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPSA id 973591E789; Mon, 8 Mar 2021 17:52:19 -0500 (EST) Subject: Re: [PATCH v2 3/5] gdb: update the docs for add_cmd and do_add_cmd to match reality To: Marco Barisione , gdb-patches@sourceware.org References: <20210108100706.96190-1-mbarisione@undo.io> <20210125112649.56362-1-mbarisione@undo.io> <20210125112649.56362-4-mbarisione@undo.io> From: Simon Marchi Message-ID: <46adb353-2e92-ca43-2afd-beaa5b779672@polymtl.ca> Date: Mon, 8 Mar 2021 17:52:19 -0500 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.7.1 MIME-Version: 1.0 In-Reply-To: <20210125112649.56362-4-mbarisione@undo.io> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 7bit X-Poly-FromMTA: (simark.ca [158.69.221.121]) at Mon, 8 Mar 2021 22:52:19 +0000 X-Spam-Status: No, score=-10.3 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, NICE_REPLY_A, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, SPF_HELO_PASS, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 08 Mar 2021 22:52:26 -0000 Just a few nits noted below. Another good cleanup if you feel like it would be to move all the declarations of the functions defined in cli/cli-decode.c from command.h to cli/cli-decode.h. We want to standardize that a declaration in foo.h has its definition in foo.c. > diff --git a/gdb/command.h b/gdb/command.h > index 827a19637a2..df40cbf7119 100644 > --- a/gdb/command.h > +++ b/gdb/command.h > @@ -155,18 +155,44 @@ extern bool valid_user_defined_cmd_name_p (const char *name); > > extern bool valid_cmd_char_p (int c); > > -/* Const-correct variant of the above. */ > +/* Add a command named NAME in command list *LIST. > > -extern struct cmd_list_element *add_cmd (const char *, enum command_class, > + NAME and DOC are not duplicated. If they are not static string, they Two spaces after period. > + must have been allocated with xmalloc or xstrdup and the > + NAME_ALLOCATED/DOC_ALLOCATED fields must be set to 1 on the returned > + command. > + > + THECLASS is the top level category into which commands are broken down > + for "help" purposes. > + > + FUN should be the function to execute the command; it will get two I'd say "is the" instead of "should be". "should be" makes it sound like it's a suggestion but it could be something else, which is not the case. > + arguments, a character string (with leading and trailing blanks already > + eliminated) containing the command arguments, and an integer indicating > + whether input comes from a TTY or not. I think this detailed doc about the callback's parameters would be better placed in the doc comment of the cmd_const_cfunc_ftype typedef. In that doc, you could refer to the parameters using their names. > + > + DOC is a documentation string for the command. > + Its first line should be a complete sentence. > + It should start with ? for a command that is an abbreviation > + or with * for a command that most users don't need to know about. > + > + If NAME already existed in *LIST, all its hooks and aliases are moved > + to the new command. > + > + Return a pointer to the added command (not necessarily the head of > + *LIST). */ I really like the way this doc is structured, one paragraph per parameter with some space in between, very legible. Simon