[FYI] Restore parameter names in observable.h

Message ID 20191121000549.15420-1-tom@tromey.com
State New
Headers show
Series
  • [FYI] Restore parameter names in observable.h
Related show

Commit Message

Tom Tromey Nov. 21, 2019, 12:05 a.m.
Ages ago, when we switched observables to be templates, Joel asked me
to restore the parameter names that were used in the old
observer.texi.

I've finally done this.  I also updated the comments in this file to
use the GNU metasyntactic variable convention as well.

gdb/ChangeLog
2019-11-20  Tom Tromey  <tom@tromey.com>

	* observable.h: Update comments.

Change-Id: Id71bea7a7fcaa8f5d4491f33aa8861c56ba9c3f0
---
 gdb/ChangeLog    |   4 ++
 gdb/observable.h | 162 ++++++++++++++++++++++++-----------------------
 2 files changed, 86 insertions(+), 80 deletions(-)

-- 
2.17.2

Comments

Tom Tromey Nov. 21, 2019, 12:07 a.m. | #1
>>>>> "Tom" == Tom Tromey <tom@tromey.com> writes:


Tom> Ages ago, when we switched observables to be templates, Joel asked me
Tom> to restore the parameter names that were used in the old
Tom> observer.texi.

Tom> I've finally done this.  I also updated the comments in this file to
Tom> use the GNU metasyntactic variable convention as well.

LOL I didn't compile this.
I think it has to be redone with the names in comments.

Tom

Patch

diff --git a/gdb/observable.h b/gdb/observable.h
index b58966ea90b..215b9606d0e 100644
--- a/gdb/observable.h
+++ b/gdb/observable.h
@@ -35,9 +35,9 @@  namespace gdb
 namespace observers
 {
 
-/* The inferior has stopped for real.  The bs argument describes the
+/* The inferior has stopped for real.  The BS argument describes the
    breakpoints were are stopped at, if any.  Second argument
-   print_frame non-zero means display the location where the
+   PRINT_FRAME non-zero means display the location where the
    inferior has stopped.
 
    gdb notifies all normal_stop observers when the inferior execution
@@ -49,19 +49,19 @@  namespace observers
    condition that is not met.  If the breakpoint has any associated
    commands list, the commands are executed after the notification is
    emitted.  */
-extern observable<struct bpstats *, int> normal_stop;
+extern observable<struct bpstats *bs, int print_frame> normal_stop;
 
 /* The inferior was stopped by a signal.  */
-extern observable<enum gdb_signal> signal_received;
+extern observable<enum gdb_signal siggnal> signal_received;
 
 /* We are done with a step/next/si/ni command.  */
 extern observable<> end_stepping_range;
 
 /* The inferior was terminated by a signal.  */
-extern observable<enum gdb_signal> signal_exited;
+extern observable<enum gdb_signal siggnal> signal_exited;
 
 /* The inferior program is finished.  */
-extern observable<int> exited;
+extern observable<int exitstatus> exited;
 
 /* Reverse execution: target ran out of history info.  */
 extern observable<> no_history;
@@ -73,7 +73,7 @@  extern observable<> sync_execution_done;
 extern observable<> command_error;
 
 /* The target's register contents have changed.  */
-extern observable<struct target_ops *> target_changed;
+extern observable<struct target_ops *target> target_changed;
 
 /* The executable being debugged by GDB has changed: The user
    decided to debug a different program, or the program he was
@@ -86,147 +86,149 @@  extern observable<> executable_changed;
    instruction.  For 'attach' and 'core', gdb calls this observer
    immediately after connecting to the inferior, and before any
    information on the inferior has been printed.  */
-extern observable<struct target_ops *, int> inferior_created;
+extern observable<struct target_ops *target, int from_tty> inferior_created;
 
 /* The status of process record for inferior inferior in gdb has
-   changed.  The process record is started if started is true, and
-   the process record is stopped if started is false.
+   changed.  The process record is started if STARTED is true, and
+   the process record is stopped if STARTED is false.
 
-   When started is true, method indicates the short name of the
+   When STARTED is true, METHOD indicates the short name of the
    method used for recording.  If the method supports multiple
-   formats, format indicates which one is being used, otherwise it
-   is NULL.  When started is false, they are both NULL.  */
-extern observable<struct inferior *, int, const char *, const char *>
+   formats, FORMAT indicates which one is being used, otherwise it
+   is NULL.  When STARTED is false, they are both NULL.  */
+extern observable<struct inferior *inferior, int started,
+		  const char *method, const char *format>
     record_changed;
 
-/* The shared library specified by solib has been loaded.  Note that
+/* The shared library specified by SOLIB has been loaded.  Note that
    when gdb calls this observer, the library's symbols probably
    haven't been loaded yet.  */
-extern observable<struct so_list *> solib_loaded;
+extern observable<struct so_list *solib> solib_loaded;
 
-/* The shared library specified by solib has been unloaded.  Note
+/* The shared library specified by SOLIB has been unloaded.  Note
    that when gdb calls this observer, the library's symbols have not
    been unloaded yet, and thus are still available.  */
-extern observable<struct so_list *> solib_unloaded;
+extern observable<struct so_list *solib> solib_unloaded;
 
-/* The symbol file specified by objfile has been loaded.  Called
-   with objfile equal to NULL to indicate previously loaded symbol
+/* The symbol file specified by OBJFILE has been loaded.  Called
+   with OBJFILE equal to NULL to indicate previously loaded symbol
    table data has now been invalidated.  */
-extern observable<struct objfile *> new_objfile;
+extern observable<struct objfile *objfile> new_objfile;
 
-/* The object file specified by objfile is about to be freed.  */
-extern observable<struct objfile *> free_objfile;
+/* The object file specified by OBJFILE is about to be freed.  */
+extern observable<struct objfile *objfile> free_objfile;
 
-/* The thread specified by t has been created.  */
-extern observable<struct thread_info *> new_thread;
+/* The thread specified by T has been created.  */
+extern observable<struct thread_info *t> new_thread;
 
-/* The thread specified by t has exited.  The silent argument
+/* The thread specified by T has exited.  The SILENT argument
    indicates that gdb is removing the thread from its tables without
    wanting to notify the user about it.  */
-extern observable<struct thread_info *, int> thread_exit;
+extern observable<struct thread_info *t, int silent> thread_exit;
 
-/* An explicit stop request was issued to ptid.  If ptid equals
+/* An explicit stop request was issued to PTID.  If PTID equals
    minus_one_ptid, the request applied to all threads.  If
-   ptid_is_pid(ptid) returns true, the request applied to all
-   threads of the process pointed at by ptid.  Otherwise, the
-   request applied to the single thread pointed at by ptid.  */
-extern observable<ptid_t> thread_stop_requested;
+   ptid_is_pid(PTID) returns true, the request applied to all
+   threads of the process pointed at by PTID.  Otherwise, the
+   request applied to the single thread pointed at by PTID.  */
+extern observable<ptid_t ptid> thread_stop_requested;
 
-/* The target was resumed.  The ptid parameter specifies which
+/* The target was resumed.  The PTID parameter specifies which
    thread was resume, and may be RESUME_ALL if all threads are
    resumed.  */
-extern observable<ptid_t> target_resumed;
+extern observable<ptid_t ptid> target_resumed;
 
 /* The target is about to be proceeded.  */
 extern observable<> about_to_proceed;
 
-/* A new breakpoint b has been created.  */
-extern observable<struct breakpoint *> breakpoint_created;
+/* A new breakpoint B has been created.  */
+extern observable<struct breakpoint *b> breakpoint_created;
 
-/* A breakpoint has been destroyed.  The argument b is the
+/* A breakpoint has been destroyed.  The argument B is the
    pointer to the destroyed breakpoint.  */
-extern observable<struct breakpoint *> breakpoint_deleted;
+extern observable<struct breakpoint *b> breakpoint_deleted;
 
-/* A breakpoint has been modified in some way.  The argument b
+/* A breakpoint has been modified in some way.  The argument B
    is the modified breakpoint.  */
-extern observable<struct breakpoint *> breakpoint_modified;
+extern observable<struct breakpoint *b> breakpoint_modified;
 
-/* The trace frame is changed to tfnum (e.g., by using the 'tfind'
-   command).  If tfnum is negative, it means gdb resumes live
+/* The trace frame is changed to TFNUM (e.g., by using the 'tfind'
+   command).  If TFNUM is negative, it means gdb resumes live
    debugging.  The number of the tracepoint associated with this
-   traceframe is tpnum.  */
-extern observable<int, int> traceframe_changed;
+   traceframe is TPNUM.  */
+extern observable<int tfnum, int tpnum> traceframe_changed;
 
-/* The current architecture has changed.  The argument newarch is a
+/* The current architecture has changed.  The argument NEWARCH is a
    pointer to the new architecture.  */
-extern observable<struct gdbarch *> architecture_changed;
+extern observable<struct gdbarch *newarch> architecture_changed;
 
-/* The thread's ptid has changed.  The old_ptid parameter specifies
-   the old value, and new_ptid specifies the new value.  */
-extern observable<ptid_t, ptid_t> thread_ptid_changed;
+/* The thread's ptid has changed.  The OLD_PTID parameter specifies
+   the old value, and NEW_PTID specifies the new value.  */
+extern observable<ptid_t old_ptid, ptid_t new_ptid> thread_ptid_changed;
 
-/* The inferior inf has been added to the list of inferiors.  At
+/* The inferior INF has been added to the list of inferiors.  At
    this point, it might not be associated with any process.  */
-extern observable<struct inferior *> inferior_added;
+extern observable<struct inferior *inf> inferior_added;
 
-/* The inferior identified by inf has been attached to a
+/* The inferior identified by INF has been attached to a
    process.  */
-extern observable<struct inferior *> inferior_appeared;
+extern observable<struct inferior *inf> inferior_appeared;
 
-/* Either the inferior associated with inf has been detached from
+/* Either the inferior associated with INF has been detached from
    the process, or the process has exited.  */
-extern observable<struct inferior *> inferior_exit;
+extern observable<struct inferior *inf> inferior_exit;
 
-/* The inferior inf has been removed from the list of inferiors.
-   This method is called immediately before freeing inf.  */
-extern observable<struct inferior *> inferior_removed;
+/* The inferior INF has been removed from the list of inferiors.
+   This method is called immediately before freeing INF.  */
+extern observable<struct inferior *inf> inferior_removed;
 
-/* Bytes from data to data + len have been written to the inferior
-   at addr.  */
-extern observable<struct inferior *, CORE_ADDR, ssize_t, const bfd_byte *>
+/* Bytes from DATA to DATA + LEN have been written to the inferior
+   at ADDR.  */
+extern observable<struct inferior *inferior, CORE_ADDR addr, ssize_t len,
+		  const bfd_byte *data>
     memory_changed;
 
-/* Called before a top-level prompt is displayed.  current_prompt is
+/* Called before a top-level prompt is displayed.  CURRENT_PROMPT is
    the current top-level prompt.  */
-extern observable<const char *> before_prompt;
+extern observable<const char *current_prompt> before_prompt;
 
 /* Variable gdb_datadir has been set.  The value may not necessarily
    change.  */
 extern observable<> gdb_datadir_changed;
 
 /* The parameter of some 'set' commands in console are changed.
-   This method is called after a command 'set param value'.  param
-   is the parameter of 'set' command, and value is the value of
+   This method is called after a command 'set param value'.  PARAM
+   is the parameter of 'set' command, and VALUE is the value of
    changed parameter.  */
-extern observable<const char *, const char *> command_param_changed;
+extern observable<const char *param, const char *value> command_param_changed;
 
-/* The new trace state variable tsv is created.  */
-extern observable<const struct trace_state_variable *> tsv_created;
+/* The new trace state variable TSV is created.  */
+extern observable<const struct trace_state_variable *tsv> tsv_created;
 
-/* The trace state variable tsv is deleted.  If tsv is NULL, all
+/* The trace state variable TSV is deleted.  If TSV is NULL, all
    trace state variables are deleted.  */
-extern observable<const struct trace_state_variable *> tsv_deleted;
+extern observable<const struct trace_state_variable *tsv> tsv_deleted;
 
-/* The trace state value tsv is modified.  */
-extern observable<const struct trace_state_variable *> tsv_modified;
+/* The trace state value TSV is modified.  */
+extern observable<const struct trace_state_variable *tsv> tsv_modified;
 
-/* An inferior function at address is about to be called in thread
-   thread.  */
-extern observable<ptid_t, CORE_ADDR> inferior_call_pre;
+/* An inferior function at ADDRESS is about to be called in thread
+   THREAD.  */
+extern observable<ptid_t thread, CORE_ADDR address> inferior_call_pre;
 
-/* The inferior function at address has just been called.  This
+/* The inferior function at ADDRESS has just been called.  This
    observer is called even if the inferior exits during the call.
-   thread is the thread in which the function was called, which may
+   THREAD is the thread in which the function was called, which may
    be different from the current thread.  */
-extern observable<ptid_t, CORE_ADDR> inferior_call_post;
+extern observable<ptid_t thread, CORE_ADDR address> inferior_call_post;
 
 /* A register in the inferior has been modified by the gdb user.  */
-extern observable<struct frame_info *, int> register_changed;
+extern observable<struct frame_info *frame, int regnum> register_changed;
 
 /* The user-selected inferior, thread and/or frame has changed.  The
    user_select_what flag specifies if the inferior, thread and/or
    frame has changed.  */
-extern observable<user_selected_what> user_selected_context_changed;
+extern observable<user_selected_what selection> user_selected_context_changed;
 
 /* This is notified when the source styling setting has changed and
    should be reconsulted.  */