Re: [RFA/Ada] Implement Ada tasking support

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Mon, 22 Sep 2008 16:32:09 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> 
> +      if (warn_if_null)
> +        printf_filtered (_("Your application does not use any Ada task.\n"));
                                                                     ^^^^
"tasks", I think.

> +  add_info ("tasks", info_tasks_command,
> +            _("\
> +Without argument: list all known Ada tasks, with status information.\n\
> +info tasks N: print detailed information of task N."));

IMO, this is not a good documentation string: the first line is
supposed to describe the whole command in short, not only one of its
options.  I suggest to rewrite this (and others) along these lines.

Also, I think the first line cannot have commas or periods except at
the end of the line, since various HELP commands, like `apropos',
display the text up to the first comma or period.

> +@table @asis
> +@item ID
> +Represents gdb's internal task number.
              ^^^
What happened to @value{GDBN}?

> +@item State
> +Current state of the task.
> +
> +@itemize @bullet

Why @itemize and not @table?  I think the latter would be better.

> +@item
> +Accepting RV with @var{taskno}: the task is accepting a rendez-vous with the
> +task @var{taskno}

Period missing at the end of this sentence.

> +@item task
> +@kindex task

"task" is such a generic term that I'd suggest qualifying this index
entry:

  @kindex task@r{ (Ada)}

> +@cindex current task ID

Same here: qualify with "Ada".

> +@kindex task @var{taskno}

There's no need to index all the varieties of a command; one variety
is enough.  Especially since these two entries are on the same page or
on consecutive pages.

> +@cindex task switching

Again, please qualify.

> +This command is like the @code{thread @var{threadno}}
> +command (@pxref{Threads}). It switches the context of debugging
                            ^^
Two spaces needed here.

> +memory writes in order to provide Ada tasking support.  When inspecting
> +a core file, this means that the core file must be opened with
> +read-write privileges, using the command @samp{"set write on"}.

Please put here a cross-reference to the description of "set write
on".

Also, the write markup for this is

   using the command @kbd{set write on}

(@kbd and no quotes).

Other than these gotchas, the documentation patch is approved.

Thanks.