[master] 0e8180c12 doc: Document the $Alias stanza

[Dridi Boukelmoune]

commit 0e8180c12670c64da5344ce52af768c546199000
Author: Dridi Boukelmoune <dridi.boukelmoune at gmail.com>
Date:   Mon Feb 20 08:10:46 2023 +0100

    doc: Document the $Alias stanza

diff --git a/doc/sphinx/reference/vmod.rst b/doc/sphinx/reference/vmod.rst
index 10460cd7b..a4437396d 100644
--- a/doc/sphinx/reference/vmod.rst
+++ b/doc/sphinx/reference/vmod.rst
@@ -264,6 +264,29 @@ managing instances, in particular their memory management. As the
 lifetime of object instances is the vcl, they will usually be
 allocated from the heap.
 
+Deprecated Aliases
+------------------
+
+The ``$Alias`` stanza offers a mechanism to rename a function or an
+object's method without removing the previous name. This allows name
+changes to maintain compatibility until the alias is dropped.
+
+The syntax for a function is::
+
+    $Alias deprecated_function original_function
+
+    [description]
+
+The syntax for a method is::
+
+    $Alias .deprecated_method object.original_method
+
+    [description]
+
+The ``$Alias`` stanza can appear anywhere, this allows grouping them
+in a dedicated "deprecated" section of their manual. The optional
+description can be used to explain why a function was renamed.
+
 .. _ref-vmod-vcl-c-types:
 
 VCL and C data types