From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 5FAC0C43217 for ; Fri, 25 Mar 2022 15:14:00 +0000 (UTC) Received: from localhost ([::1]:37366 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nXldX-0003Yb-9q for qemu-devel@archiver.kernel.org; Fri, 25 Mar 2022 11:13:59 -0400 Received: from eggs.gnu.org ([209.51.188.92]:40346) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nXlbI-0001py-Ff for qemu-devel@nongnu.org; Fri, 25 Mar 2022 11:11:40 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:43013) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nXlbD-0006XP-K8 for qemu-devel@nongnu.org; Fri, 25 Mar 2022 11:11:37 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1648221094; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=KvuhQVYZFvpcoGt0K8QuKFoZK90lq7ElgtihbTpkqZ4=; b=SJXle9Fv7GNRnKBBRLpOpgJLfDMtkKLevt30G5g89DJTMXA/wGY5Sck/2DI6MrmqW/Y99w aW8i0OWT747shrFcvEgDKajA6srsGDjCZIzEdn9GuDp1WZBuu2fpoCZAPJ4rYGfkLgWkwQ bvdpqtrGCuMdEf5Eri1w9f9o1oc9X2c= Received: from mail-vs1-f69.google.com (mail-vs1-f69.google.com [209.85.217.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-400-yHZAio9aML-nWm3rRNZq9g-1; Fri, 25 Mar 2022 11:11:33 -0400 X-MC-Unique: yHZAio9aML-nWm3rRNZq9g-1 Received: by mail-vs1-f69.google.com with SMTP id s18-20020a67df12000000b00324c903413cso1750973vsk.23 for ; Fri, 25 Mar 2022 08:11:32 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=KvuhQVYZFvpcoGt0K8QuKFoZK90lq7ElgtihbTpkqZ4=; b=Rhq2ViD7PAljr8UPi+qVOXhixMEdBg16r6KfZg1mBLrCg91tNKu5LVKRUoYO992ofP 5evKPAjbsn0gTyG33pt0Aw0O3u1RdP4r99p4ORx8j+cvi4R/MNSJWNdy+j9BoZJWLU2j 8RT/6wNLj/ZxU0ZJ62z5/9duoPwtF28mhNymaT3TpVIfoO7DaIb1zCrovnzUKECHWtS8 yzU1LDmZvyJM89NqWs6mgDDAcA8+jRf8k0m7YoM8WGovOlxnizmClycjVIrIo2NX1L6q hUHX8/wyKKSh19i8L0rxrxq7255Kj+d9Fc6xpyPJmAzvp9FUXeP7RbFZTCfRTYnP00zh OTwg== X-Gm-Message-State: AOAM53392PxbVnDjHw5AfFJS+l5CgIgsFKK7Sy95uRJgklSHbZzYnwQN u7CEsBuhEJKauHd1KLa2NeaqTLu80ItRoN9IYLZybusAy+uqI3l+/Pe1OgQ5fjss5PgQmjvmZ3g sSrOW37tfGku0yDHfeMR7QomaIlpwTjI= X-Received: by 2002:a05:6122:2186:b0:33f:c30b:9b46 with SMTP id j6-20020a056122218600b0033fc30b9b46mr3896593vkd.26.1648221092410; Fri, 25 Mar 2022 08:11:32 -0700 (PDT) X-Google-Smtp-Source: ABdhPJx/IKOazYjRnZMGTyw4u4jjX0bYrbtW+lRNq8ArggjTxlgW1b8vQHH/+A0BJiBWF3dS/qVXLzPjwYv83m6uyZ0= X-Received: by 2002:a05:6122:2186:b0:33f:c30b:9b46 with SMTP id j6-20020a056122218600b0033fc30b9b46mr3896558vkd.26.1648221092103; Fri, 25 Mar 2022 08:11:32 -0700 (PDT) MIME-Version: 1.0 References: <20220324175015.232794-1-victortoso@redhat.com> <20220324175015.232794-2-victortoso@redhat.com> <87tubmnrde.fsf@pond.sub.org> In-Reply-To: <87tubmnrde.fsf@pond.sub.org> From: John Snow Date: Fri, 25 Mar 2022 11:11:23 -0400 Message-ID: Subject: Re: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO To: Markus Armbruster Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=jsnow@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: multipart/alternative; boundary="000000000000b4d5e005db0c60e9" Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -21 X-Spam_score: -2.2 X-Spam_bar: -- X-Spam_report: (-2.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.082, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Eric Blake , Victor Toso , qemu-devel Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: "Qemu-devel" --000000000000b4d5e005db0c60e9 Content-Type: text/plain; charset="UTF-8" On Fri, Mar 25, 2022, 8:33 AM Markus Armbruster wrote: > Victor Toso 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 > > --- > > 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 > > 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: Reviewed-by: John Snow > --000000000000b4d5e005db0c60e9 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable


On Fri, Mar 25, 2022, 8:33 AM Markus Armbruster <armbru@redhat.com> wrote:
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>
> ---
>=C2=A0 qapi/block-export.json | 10 +++++-----
>=C2=A0 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 @@
>=C2=A0 #
>=C2=A0 # @hard: Drop all connections immediately and remove export.
>=C2=A0 #
> -# Potential additional modes to be added in the future:
> +# TODO: Potential additional modes to be added in the future:
>=C2=A0 #
> -# hide: Just hide export from new clients, leave existing connections= as is.
> -# Remove export after all clients are disconnected.
> +#=C2=A0 =C2=A0 =C2=A0 =C2=A0hide: Just hide export from new clients, = leave existing connections as is.
> +#=C2=A0 =C2=A0 =C2=A0 =C2=A0Remove export after all clients are disco= nnected.
>=C2=A0 #
> -# soft: Hide export from new clients, answer with ESHUTDOWN for all f= urther
> -# requests from existing clients.
> +#=C2=A0 =C2=A0 =C2=A0 =C2=A0soft: Hide export from new clients, answe= r with ESHUTDOWN for all further
> +#=C2=A0 =C2=A0 =C2=A0 =C2=A0requests from existing clients.
>=C2=A0 #
>=C2=A0 # Since: 2.12
>=C2=A0 ##

Reviewed-by: Markus Armbruster <armbru@redhat.com>

Doc comments embed user documentation in the source code.=C2=A0 The doc
generator extracts it.

TODOs are generally for developers.=C2=A0 Should the doc generator suppress=
TODO sections?

Needs an audit to make sure we're using it consistently w= ith that semantic, but broadly it's probably a good idea to squelch &qu= ot;internal" todos, yes.=C2=A0

Things like "Watch out, were definitely gonna deprecate th= is soon probably maybe!" can stay outside of the TODO section. (Someti= mes 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:

Reviewed-b= y: John Snow <jsnow@redhat.com&g= t;
--000000000000b4d5e005db0c60e9--