[master] 4688edd83 doc: Document changes to the workspace API

[Dridi Boukelmoune]

commit 4688edd8362e13ccafadebd1f6e90a30ec346228
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Tue Sep 8 11:09:06 2020 +0200

    doc: Document changes to the workspace API
    
    In addition, soften the WS_Front() deprecation and keep the new WS_Id()
    function internal.

diff --git a/bin/varnishd/cache/cache.h b/bin/varnishd/cache/cache.h
index 32c4972fa..40fafc766 100644
--- a/bin/varnishd/cache/cache.h
+++ b/bin/varnishd/cache/cache.h
@@ -795,13 +795,11 @@ int WS_Overflowed(const struct ws *ws);
 const char *WS_Printf(struct ws *ws, const char *fmt, ...) v_printflike_(2, 3);
 int WS_Inside(const struct ws *, const void *, const void *);
 void WS_Assert_Allocated(const struct ws *ws, const void *ptr, ssize_t len);
-void WS_Id(const struct ws *ws, char *id);
 
 void WS_VSB_new(struct vsb *, struct ws *);
 char *WS_VSB_finish(struct vsb *, struct ws *, size_t *);
 
 /* REL_20210315 remove */
-static inline char* WS_Front(const struct ws *) v_deprecated_;
 static inline char*
 WS_Front(const struct ws *ws)
 {
diff --git a/bin/varnishd/cache/cache_varnishd.h b/bin/varnishd/cache/cache_varnishd.h
index ececc96aa..9a68f4229 100644
--- a/bin/varnishd/cache/cache_varnishd.h
+++ b/bin/varnishd/cache/cache_varnishd.h
@@ -464,6 +464,7 @@ void VMOD_Panic(struct vsb *);
 void WRK_Init(void);
 
 /* cache_ws.c */
+void WS_Id(const struct ws *ws, char *id);
 void WS_Panic(const struct ws *ws, struct vsb *vsb);
 static inline int
 WS_IsReserved(const struct ws *ws)
diff --git a/doc/sphinx/whats-new/changes-trunk.rst b/doc/sphinx/whats-new/changes-trunk.rst
index fbda9d6b9..afbbd0bb2 100644
--- a/doc/sphinx/whats-new/changes-trunk.rst
+++ b/doc/sphinx/whats-new/changes-trunk.rst
@@ -67,6 +67,23 @@ varnishtest
 Changes for developers and VMOD authors
 =======================================
 
+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
+introduced as a replacement.
+
+On the topic of workspace reservation, the ``WS_Front()`` function is
+now deprecated in favor of ``WS_Reservation()``. The two functions
+behave similarly, but the latter ensures that it is only ever called
+during a reservation. There was no legitimate reason to access the
+workspace's front outside of a reservation.
+
+In a scenario where a reservation is made in a part of the code, but
+used somewhere else, it is possible to later query the size with the
+new ``WS_ReservationSize()`` function.
+
+The return value for ``WS_Printf()`` is now a constant string.
+
 **XXX changes concerning VRT, the public APIs, source code organization,
 builds etc.**
 
diff --git a/include/vrt.h b/include/vrt.h
index 2e5cc2d7d..f80d5fa47 100644
--- a/include/vrt.h
+++ b/include/vrt.h
@@ -60,7 +60,6 @@
  *	[cache.h] WS_ReservationSize() added
  *	[cache.h] WS_Front() deprecated
  *	[cache.h] WS_Reservation() added
- *	[cache.h] WS_Id() added
  * 11.0 (2020-03-16)
  *	Changed type of vsa_suckaddr_len from int to size_t
  *	New prefix_{ptr|len} fields in vrt_backend