Re: [PATCH, MPX, 2/X] Pointers Checker [1/25] Hooks

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Mon, 21 Oct 2013, Ilya Enkovich wrote:

> +DEFHOOK
> +(builtin_chkp_function,
> + "Pointers checker instrumentation pass uses this hook to obtain\n\
> +target-specific functions which implement specified generic checker\n\
> +builtins.",
> + tree, (unsigned fcode),
> + default_builtin_chkp_function)

I don't think that's enough detail.  The audience for this hook 
description is back-end maintainers wanting to implement such hooks for 
their back ends, and the hook description should give sufficient 
information to do so.  This description says nothing at all about the 
semantics of the hook argument or return value.

If it seems difficult to describe things sufficiently in the context of 
individual hook descriptions, maybe an overview of the feature and 
implementation approach is needed as a new section in the internals 
manual, with hook descriptions then referring to that section, or going in 
appropriate places within that section (if the section is in tm.texi.in).

> +DEFHOOK
> +(fn_abi_va_list_bounds_size,
> + "This hook returns size for va_list object or integer_zero_node if\n\
> +it does not have any (e.g. is scalar pointer to the stack).",
> + tree, (tree fndecl),
> + default_fn_abi_va_list_bounds_size)

@code{va_list}, @code{integer_zero_node}, specify semantics of fndecl 
argument.

>  DEFHOOK
> +(load_bounds_for_arg,
> + "This hook is used to emit insn to load arg's bounds\n\
> +in case bounds are not passed on register.  Return loaded bounds",
> + rtx, (rtx, rtx, rtx),
> + default_load_bounds_for_arg)

You need to name all the arguments and explain their semantics by name in 
the documentation (which should end with ".").

> +DEFHOOK
> +(store_bounds_for_arg,
> + "This hook is used to emit insn to store arg's bounds\n\
> +in case bounds are not passed on register.",
> + void, (rtx, rtx, rtx, rtx),
> + default_store_bounds_for_arg)

Likewise.

-- 
Joseph S. Myers
joseph@codesourcery.com