[master] 4d6ca8c5f doc: A word on VSC_Arg()

[Dridi Boukelmoune]

commit 4d6ca8c5f426a8277add3ca34f5dc1f282177442
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Fri Sep 11 22:02:22 2020 +0200

    doc: A word on VSC_Arg()
    
    And a quick note on the workspace API plus homework for later.

diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index 0f150d59c..29ccd5a5b 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -152,6 +152,9 @@ disruption.
 Changes for developers and VMOD authors
 =======================================
 
+VMODs
+~~~~~
+
 The workspace API saw a number of changes in anticipation of a future
 inclusion in VRT. The deprecated ``WS_Reserve()`` function was finally
 removed, the functions ``WS_ReserveSize()`` and ``WS_ReserveAll()`` were
@@ -169,10 +172,31 @@ new ``WS_ReservationSize()`` function.
 
 The return value for ``WS_Printf()`` is now a constant string.
 
+In general, accessing any field of ``struct ws`` is strongly discouraged
+and if the workspace API doesn't satisfy all your needs please bring
+that to our attention.
+
 VMOD authors who would like to generate VCC files can now use the
 ``VARNISH_VMODS_GENERATED()`` macro from ``varnish.m4`` for autotools
 builds.
 
+libvarnishapi
+~~~~~~~~~~~~~
+
+There are three new VSC arguments that can be set with the ``VSC_Arg()``
+function:
+
+- ``'I'`` to include counters matching a glob pattern
+- ``'X'`` to exclude counters matching a glob pattern
+- ``'R'`` to include required counters regardless of ``'I'`` and ``'X'``
+
+The ``'f'`` argument is now deprecated and emulated with ``'I'`` and ``'X'``.
+Filtering with ``'f'`` used to check exclusions first and then inclusions,
+they are all tested in order and the first to match determines the outcome.
+
+The ``'R'`` argument takes precedence over regular filtering and can be used
+to ensure that some counters are present regardless of user configuration.
+
 **XXX changes concerning VRT, the public APIs, source code organization,
 builds etc.**
 
diff --git a/doc/sphinx/whats-new/upgrading-trunk.rst b/doc/sphinx/whats-new/upgrading-trunk.rst
index 9922355b4..27cb67c94 100644
--- a/doc/sphinx/whats-new/upgrading-trunk.rst
+++ b/doc/sphinx/whats-new/upgrading-trunk.rst
@@ -61,6 +61,9 @@ After::
     }
   }
 
+TODO: a word on ``varnishstat -f`` being deprecated and ``-{I,X}`` being
+order-sensitive.
+
 VSL
 ===
 
@@ -73,4 +76,9 @@ The new query would be::
 
     varnishlog -q 'BackendClose[2] ~ www and BackendClose[3] eq recycle'
 
+libvarnishapi
+=============
+
+TODO: a similar note as ``varnishstat -f`` for ``VSC_Arg('f')``.
+
 *eof*