From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id cXrXCAqrDmBNfgAAWB0awg (envelope-from ) for ; Mon, 25 Jan 2021 06:27:06 -0500 Received: by simark.ca (Postfix, from userid 112) id 087E01EF82; Mon, 25 Jan 2021 06:27:06 -0500 (EST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on simark.ca X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RDNS_NONE,URIBL_BLOCKED autolearn=no autolearn_force=no version=3.4.2 Received: from sourceware.org (unknown [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 40A2A1EF80 for ; Mon, 25 Jan 2021 06:27:05 -0500 (EST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 679EC394D828; Mon, 25 Jan 2021 11:27:04 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 679EC394D828 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sourceware.org; s=default; t=1611574024; bh=84BhoS4BkBymeH69X5ZpWR9hd8q8AlmoboIPjVHOeg8=; h=To:Subject:Date:In-Reply-To:References:List-Id:List-Unsubscribe: List-Archive:List-Post:List-Help:List-Subscribe:From:Reply-To: From; b=EdjJf170Xx2z8auI+1LHKEWDsDoo2XTaVRvTeYqKfmmCPPUJiaSsLcXhgOCS29e7W ZFzIRy/nK/SUMHzMDn5288kJ2NtBcpH/JQKw2VdEcM9PIYTDEnLeLKohxOPJv/e8Oc WbdBmJdJkpZARU55A1rxdjb1stx/bFDQu88jy3+4= Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by sourceware.org (Postfix) with ESMTPS id 0AC37394C030 for ; Mon, 25 Jan 2021 11:27:02 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 0AC37394C030 Received: by mail-wr1-x434.google.com with SMTP id v15so11946253wrx.4 for ; Mon, 25 Jan 2021 03:27:01 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=84BhoS4BkBymeH69X5ZpWR9hd8q8AlmoboIPjVHOeg8=; b=K2rCJQWfNeoPZvGQ6rnOJq4EcPwWjP/vrodIsXf/JeTcCFxok5OXEXPASPJsT+19kN aImVrTlwlUmVolNc0VtBPH/Kaix3j6aTVyZk+rHNNaGaYN3mfp9BBbBFQpUA52SCp9yM FW7/es6VJakUtNIjanX3+Z666diGIV8wdjQO/+51DGfFnABXpIZ7GT7xW68zrnwfhba3 DL8FN1ZQ2gBh61Ky0MVBBTVMtiNb5KtbZ6k0P6fmvEzY5YgXdGSj1hw9fLhfjhA8zZlW GHLi1EZroD1IVmB+eer7ire46aexlIqy1K0M7B6v7ll4RKse7tei9ljMl7bKA4zfX4rc UZ5Q== X-Gm-Message-State: AOAM530zAVdNN5dkDwa6I6ND89IQ7RdcJFziv5tl65dJkCfwORAuV+a/ +WLyR7tLHut6HcoP4vt/xlvUF9BEAS2umGz/1Vf8A0RAWw0pPI3x62UB/dBjyFXxKXPFrUCPorl 8+Hbcvx5v4h0tOLUue8M8qtalgeIMiU8LHbSQaS0xRQnEfBNnRzIl/XrmAYKMopOgew9mdsRmfH vR X-Google-Smtp-Source: ABdhPJx4kXR91Vey1l20++CBTkyTx5i1iD8X0YZcENSPEI+WzzLBjWX1kRHAeZBRVmrkf3tIj9OZ3g== X-Received: by 2002:adf:f60f:: with SMTP id t15mr405012wrp.53.1611574020657; Mon, 25 Jan 2021 03:27:00 -0800 (PST) Received: from focaccia.undoers.io (cpc159317-cmbg20-2-0-cust151.5-4.cable.virginm.net. [81.111.29.152]) by smtp.gmail.com with ESMTPSA id q2sm20648220wma.6.2021.01.25.03.26.59 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Mon, 25 Jan 2021 03:27:00 -0800 (PST) To: gdb-patches@sourceware.org Subject: [PATCH v2 3/5] gdb: update the docs for add_cmd and do_add_cmd to match reality Date: Mon, 25 Jan 2021 11:26:47 +0000 Message-Id: <20210125112649.56362-4-mbarisione@undo.io> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20210125112649.56362-1-mbarisione@undo.io> References: <20210108100706.96190-1-mbarisione@undo.io> <20210125112649.56362-1-mbarisione@undo.io> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit 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: Marco Barisione via Gdb-patches Reply-To: Marco Barisione Errors-To: gdb-patches-bounces@sourceware.org Sender: "Gdb-patches" It looks like the docs for add_cmd ended up being the docs for do_add_cmd. Moreover, they were outdated. gdb/ChangeLog: * cli/cli-decode.c (do_add_cmd): Remove outdated documentation and refer to the documentation for add_cmd. (add_cmd): Add comment referring to the docs in command.h. * command.h (add_cmd): Add updated documentation. --- gdb/cli/cli-decode.c | 22 +++++----------------- gdb/command.h | 40 +++++++++++++++++++++++++++++++++------- 2 files changed, 38 insertions(+), 24 deletions(-) diff --git a/gdb/cli/cli-decode.c b/gdb/cli/cli-decode.c index f48a9add4d4..6e076c4519f 100644 --- a/gdb/cli/cli-decode.c +++ b/gdb/cli/cli-decode.c @@ -160,23 +160,7 @@ set_cmd_completer_handle_brkchars (struct cmd_list_element *cmd, cmd->completer_handle_brkchars = func; } -/* Add element named NAME. - Space for NAME and DOC must be allocated by the caller. - CLASS 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 a character string as argument, with leading - and trailing blanks already eliminated. - - 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. - - Add this command to command list *LIST. - - Returns a pointer to the added command (not necessarily the head - of *LIST). */ +/* Like ADD_CMD, but the command function fields are not modified. */ static struct cmd_list_element * do_add_cmd (const char *name, enum command_class theclass, @@ -227,6 +211,8 @@ do_add_cmd (const char *name, enum command_class theclass, return c; } +/* See command.h. */ + struct cmd_list_element * add_cmd (const char *name, enum command_class theclass, const char *doc, struct cmd_list_element **list) @@ -237,6 +223,8 @@ add_cmd (const char *name, enum command_class theclass, return result; } +/* See command.h. */ + struct cmd_list_element * add_cmd (const char *name, enum command_class theclass, cmd_const_cfunc_ftype *fun, 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 + 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 + 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. + + 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). */ + +extern struct cmd_list_element *add_cmd (const char *name, + enum command_class theclass, cmd_const_cfunc_ftype *fun, - const char *, - struct cmd_list_element **); + const char *doc, + struct cmd_list_element **list); /* Like add_cmd, but no command function is specified. */ -extern struct cmd_list_element *add_cmd (const char *, enum command_class, - const char *, - struct cmd_list_element **); +extern struct cmd_list_element *add_cmd (const char *name, + enum command_class theclass, + const char *doc, + struct cmd_list_element **list); extern struct cmd_list_element *add_cmd_suppress_notification (const char *name, enum command_class theclass, -- 2.28.0