[RFA] target.h: Expands complete_target_initialization and add_target comments.

[Joel Brobecker]

Hello,

Pedro was kind enough to give me the clues I needed to fix a crash
caused by my targets (VxWorks - submitted here, but never pushed
due to lack of interest) to crash when trying to call
target_terminal_ours. In the end, I was missing a call to
complete_target_initialization for two or my target_ops.
I was a little confused about the purpose of add_target, and
Pedro explained it very well - it only makes sense if you want
to get it activated when the user type "target NAME ...". So,
I decided to look at the current doc, and see if that advice
could help.

This is the patch I came up with, which also expands a bit
the documentation for complete_target_initialization.

----

Expand a bit the comments to answer some questions I had when looking
at why a target of mine would not have some default methods set.

gdb/ChangeLog:

        * target.h (complete_target_initialization, add_target):
        Add comment.

Tested by rebuilding on x86_64-linux, hoping it's useful enough to
be checked in. Suggestions welcome.

OK to commit?

Thanks,
-- 
Joel

---
 gdb/target.h | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/gdb/target.h b/gdb/target.h
index 91f0cc9..db9f5c3 100644
--- a/gdb/target.h
+++ b/gdb/target.h
@@ -2006,9 +2006,13 @@ int target_verify_memory (const gdb_byte *data,
 /* Routines for maintenance of the target structures...
 
    complete_target_initialization: Finalize a target_ops by filling in
-   any fields needed by the target implementation.
+   any fields needed by the target implementation.  Unnecessary for
+   targets which are registered via add_target, as this part gets
+   taken care of then.
 
    add_target:   Add a target to the list of all possible targets.
+   This only makes sense for targets that should be activated using
+   the "target TARGET_NAME ..." command.
 
    push_target:  Make this target the top of the stack of currently used
    targets, within its particular stratum of the stack.  Result
-- 
1.8.3.2