From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id bDrPHuGuRmAPcgAAWB0awg (envelope-from ) for ; Mon, 08 Mar 2021 18:10:25 -0500 Received: by simark.ca (Postfix, from userid 112) id 70C341EF78; Mon, 8 Mar 2021 18:10:25 -0500 (EST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-1.1 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.2 Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 6898C1E789 for ; Mon, 8 Mar 2021 18:10:24 -0500 (EST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id BAB463860C3B; Mon, 8 Mar 2021 23:10:23 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BAB463860C3B DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1615245023; bh=B2pwRprhLb7q4E/WwQaB9RYMs0YQcpgPnnM5g+oVk9U=; h=Subject:To:References:Date:In-Reply-To:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=eHmQvvFdjYO2+/uYgJwHpXKAFTXZtcfxSAOShGZK7sMB9PFGh7Pb4bKshJGH4vtUc g4EquNUBj8DC75igKvrvd5c+MjUmVhoc5W3XmX/jfn6k1qvQC5LYgk5fmDjrvAYm6R QK9RrTunfKg8tZ1FYv3k39mV5jwYO3DQlezMa4e8= Received: from smtp.polymtl.ca (smtp.polymtl.ca [132.207.4.11]) by sourceware.org (Postfix) with ESMTPS id 957923860C3B for ; Mon, 8 Mar 2021 23:10:20 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 957923860C3B 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 128NAFP3008993 (version=TLSv1/SSLv3 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 8 Mar 2021 18:10:19 -0500 DKIM-Filter: OpenDKIM Filter v2.11.0 smtp.polymtl.ca 128NAFP3008993 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)) (No client certificate requested) by simark.ca (Postfix) with ESMTPSA id D668A1E789; Mon, 8 Mar 2021 18:10:14 -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> <46adb353-2e92-ca43-2afd-beaa5b779672@polymtl.ca> Message-ID: <7ec3b6f2-3ec9-ecf4-105f-52d390b4e1b5@polymtl.ca> Date: Mon, 8 Mar 2021 18:10:14 -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: <46adb353-2e92-ca43-2afd-beaa5b779672@polymtl.ca> 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 23:10:15 +0000 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: , From: Simon Marchi via Gdb-patches Reply-To: Simon Marchi Errors-To: gdb-patches-bounces@sourceware.org Sender: "Gdb-patches" On 2021-03-08 5:52 p.m., Simon Marchi via Gdb-patches wrote:> 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 > Note that if you send a new version of just that patch, we can approve merge it on its own. Simon