commands.h and cli/cli-decode.h dups (was: Re: FYI: minsyms documentation)

Pedro Alves
2012-01-03T13:21:30Z

On 01/03/2012 11:04 AM, Pedro Alves wrote:
> On 01/03/2012 02:52 AM, Joel Brobecker wrote:
>>
>> One of the issues this was supposed to solve, I was told, is that
>> you can have the same function declared in multiple .h files, which
>> is a big "ugh", but true I guess.
>
> Really big "ugh". That is insane, and we should get rid of such
> cases. Off hand, I know that command.h, and cli/ stuff declare
> some of the same functions. It's not funny to change the
> interface/prototype of such a function, update only one of the headers,
> and then find at run time you have weird crashes, because some module
> is calling the function still using the old prototype, because it pulled
> the not-updated header.

Actually looking at that code, it doesn't suffer from that particular
problem, because cli/cli-decode.h includes command.h, so if the
declarations deviated, the compiler would error.

In any case, I've found it confusing to have declarations in both
places, without a clear indication of why we have both places. I ended
up finding the rationale here:

[rfa:cli] Delete one of the two ``struct cmd_list_element''s
http://sourceware.org/ml/gdb-patches/2002-03/msg00293.html

Andrew wrote:
> (...) it does also formalize the status quo:
>
> "command.h": included by any code wanting to create commands.
>
> "cli-decode.h": included by any code implementing command internals.
>
> (...)
> Hmm, if this is ok, the comment at the top of "command.h"
> should be updated.

But the comment at the top of command.h was never updated.
(command.c is long gone from the sources.)

So this patch does the next step after Andrew's changes.
It eliminates the declaration duplication, by removing
the "public" declarations from cli-decode.h, and the private
interfaces from command.h. There are perhaps functions that
are "public" today that shouldn't, but we can move the
declarations then if we fix the uses.
It then also adds a couple of comments to the headers to
indicate their purposes.

Comments?

gdb/
2012-01-03 Pedro Alves <alves.ped@gmail.com>

* cli/cli-decode.h: Add comments.
(CMD_LIST_AMBIGUOUS): Moved to command.h
(add_cmd, add_alias_cmd, add_prefix_cmd, add_abbrev_prefix_cmd)
(set_cmd_cfunc, set_cmd_sfunc, set_cmd_completer, cmd_cfunc_eq)
(set_cmd_context, get_cmd_context, lookup_cmd, lookup_cmd_1)
(deprecate_cmd, deprecated_cmd_warning, lookup_cmd_composition)
(add_com, add_com_alias, add_info, add_info_alias)
(complete_on_cmdlist, complete_on_enum, help_list): Remove
declarations.
* command.h (CMD_LIST_AMBIGUOUS): Moved here.
(help_cmd, help_cmd_list): Delete declarations.
---

gdb/cli/cli-decode.h | 95 ++------------------------------------------------
gdb/command.h | 15 +++++---
2 files changed, 13 insertions(+), 97 deletions(-)

diff --git a/gdb/cli/cli-decode.h b/gdb/cli/cli-decode.h
index e974968..876b169 100644
--- a/gdb/cli/cli-decode.h
+++ b/gdb/cli/cli-decode.h
@@ -19,6 +19,10 @@
#if !defined (CLI_DECODE_H)
#define CLI_DECODE_H 1

+/* This file defines the private interfaces for any code implementing
+ command internals. */
+
+/* Include the public interfaces. */
#include "command.h"

struct re_pattern_buffer;
@@ -210,94 +214,6 @@ struct cmd_list_element
struct cmd_list_element *alias_chain;
};

-/* Flag for an ambiguous cmd_list result. */
-#define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)
-
-/* API to the manipulation of command lists. */
-
-extern struct cmd_list_element *add_cmd (char *, enum command_class,
- void (*fun) (char *, int), char *,
- struct cmd_list_element **);
-
-extern struct cmd_list_element *add_alias_cmd (char *, char *,
- enum command_class, int,
- struct cmd_list_element **);
-
-extern struct cmd_list_element *add_prefix_cmd (char *, enum command_class,
- void (*fun) (char *, int),
- char *,
- struct cmd_list_element **,
- char *, int,
- struct cmd_list_element **);
-
-extern struct cmd_list_element *add_abbrev_prefix_cmd (char *,
- enum command_class,
- void (*fun) (char *,
- int),
- char *,
- struct cmd_list_element
- **, char *, int,
- struct cmd_list_element
- **);
-
-/* Set the commands corresponding callback. */
-
-extern void set_cmd_cfunc (struct cmd_list_element *cmd,
- void (*cfunc) (char *args, int from_tty));
-
-extern void set_cmd_sfunc (struct cmd_list_element *cmd,
- void (*sfunc) (char *args, int from_tty,
- struct cmd_list_element * c));
-
-extern void set_cmd_completer (struct cmd_list_element *cmd,
- char **(*completer) (struct cmd_list_element *self,
- char *text, char *word));
-
-/* HACK: cagney/2002-02-23: Code, mostly in tracepoints.c, grubs
- around in cmd objects to test the value of the commands sfunc(). */
-extern int cmd_cfunc_eq (struct cmd_list_element *cmd,
- void (*cfunc) (char *args, int from_tty));
-
-/* Access to the command's local context. */
-extern void set_cmd_context (struct cmd_list_element *cmd, void *context);
-extern void *get_cmd_context (struct cmd_list_element *cmd);
-
-extern struct cmd_list_element *lookup_cmd (char **,
- struct cmd_list_element *, char *,
- int, int);
-
-extern struct cmd_list_element *lookup_cmd_1 (char **,
- struct cmd_list_element *,
- struct cmd_list_element **,
- int);
-
-extern struct cmd_list_element *
- deprecate_cmd (struct cmd_list_element *, char * );
-
-extern void
- deprecated_cmd_warning (char **);
-
-extern int
- lookup_cmd_composition (char *text,
- struct cmd_list_element **alias,
- struct cmd_list_element **prefix_cmd,
- struct cmd_list_element **cmd);
-
-extern struct cmd_list_element *add_com (char *, enum command_class,
- void (*fun) (char *, int), char *);
-
-extern struct cmd_list_element *add_com_alias (char *, char *,
- enum command_class, int);
-
-extern struct cmd_list_element *add_info (char *, void (*fun) (char *, int),
- char *);
-
-extern struct cmd_list_element *add_info_alias (char *, char *, int);
-
-extern char **complete_on_cmdlist (struct cmd_list_element *, char *, char *);
-
-extern char **complete_on_enum (const char *enumlist[], char *, char *);
-
extern void help_cmd_list (struct cmd_list_element *, enum command_class,
char *, int, struct ui_file *);

@@ -305,9 +221,6 @@ extern void help_cmd_list (struct cmd_list_element *, enum command_class,

extern void help_cmd (char *, struct ui_file *);

-extern void help_list (struct cmd_list_element *, char *,
- enum command_class, struct ui_file *);
-
extern void apropos_cmd (struct ui_file *, struct cmd_list_element *,
struct re_pattern_buffer *, char *);

diff --git a/gdb/command.h b/gdb/command.h
index 04cb751..8112b05 100644
--- a/gdb/command.h
+++ b/gdb/command.h
@@ -1,4 +1,4 @@
-/* Header file for command-reading library command.c.
+/* Header file for command creation.

Copyright (C) 1986, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2000,
2002, 2004, 2007, 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
@@ -19,6 +19,9 @@
#if !defined (COMMAND_H)
#define COMMAND_H 1

+/* This file defines the public interface for any code wanting to
+ create commands. */
+
/* Command classes are top-level categories into which commands are
broken down for "help" purposes.

@@ -106,6 +109,8 @@ struct cmd_list_element;

/* Forward-declarations of the entry-points of cli/cli-decode.c. */

+/* API to the manipulation of command lists. */
+
extern int valid_user_defined_cmd_name_p (const char *name);

extern struct cmd_list_element *add_cmd (char *, enum command_class,
@@ -168,6 +173,8 @@ extern void execute_cmd_post_hook (struct cmd_list_element *cmd);
/* Return the type of the command. */
extern enum cmd_types cmd_type (struct cmd_list_element *cmd);

+/* Flag for an ambiguous cmd_list result. */
+#define CMD_LIST_AMBIGUOUS ((struct cmd_list_element *) -1)

extern struct cmd_list_element *lookup_cmd (char **,
struct cmd_list_element *, char *,
@@ -207,15 +214,11 @@ extern char **complete_on_cmdlist (struct cmd_list_element *,
extern char **complete_on_enum (const char *enumlist[],
char *, char *);

-extern void help_cmd (char *, struct ui_file *);
+/* Functions that implement commands about CLI commands. */

extern void help_list (struct cmd_list_element *, char *,
enum command_class, struct ui_file *);

-extern void help_cmd_list (struct cmd_list_element *,
- enum command_class,
- char *, int, struct ui_file *);
-
/* Method for show a set/show variable's VALUE on FILE. If this
method isn't supplied deprecated_show_value_hack() is called (which
is not good). */