Victor Toso <victortoso@redhat.com> writes:
> @hide and @soft are potential additions which fits the TODO section
> perfectly.
>
> The main motivation is to avoid this whole block of comment entering
> the wrong section in the python parser.
>
> Signed-off-by: Victor Toso <victortoso@redhat.com>
> ---
> qapi/block-export.json | 10 +++++-----
> 1 file changed, 5 insertions(+), 5 deletions(-)
>
> diff --git a/qapi/block-export.json b/qapi/block-export.json
> index f183522d0d..1e34927f85 100644
> --- a/qapi/block-export.json
> +++ b/qapi/block-export.json
> @@ -219,13 +219,13 @@
> #
> # @hard: Drop all connections immediately and remove export.
> #
> -# Potential additional modes to be added in the future:
> +# TODO: Potential additional modes to be added in the future:
> #
> -# hide: Just hide export from new clients, leave existing connections as is.
> -# Remove export after all clients are disconnected.
> +# hide: Just hide export from new clients, leave existing connections as is.
> +# Remove export after all clients are disconnected.
> #
> -# soft: Hide export from new clients, answer with ESHUTDOWN for all further
> -# requests from existing clients.
> +# soft: Hide export from new clients, answer with ESHUTDOWN for all further
> +# requests from existing clients.
> #
> # Since: 2.12
> ##
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Doc comments embed user documentation in the source code. The doc
generator extracts it.
TODOs are generally for developers. Should the doc generator suppress
TODO sections?
Needs an audit to make sure we're using it consistently with that semantic, but broadly it's probably a good idea to squelch "internal" todos, yes.
Things like "Watch out, were definitely gonna deprecate this soon probably maybe!" can stay outside of the TODO section. (Sometimes heads up are legitimate, even if most won't read them. the faithful and diligent will be rewarded with painless upgrades.)
Anyway, if Markus is happy with this change, I am too, I was just curious to know if there were bigger cleanups to do here and what the impact was.
Anyway: