[PATCH] Document _canonical_paths.

[Daniel Shahaf <d.s@xxxxxxxxxxxxxxxxxx>]

This mostly copy-pastes and adds markup, however, the positional arguments
are now annotated optional, and a ')' was added.
---
 Completion/Unix/Type/_canonical_paths | 13 -------------
 Doc/Zsh/compsys.yo                    | 15 +++++++++++++++
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/Completion/Unix/Type/_canonical_paths b/Completion/Unix/Type/_canonical_paths
index e4a725b..7dc6b78 100644
--- a/Completion/Unix/Type/_canonical_paths
+++ b/Completion/Unix/Type/_canonical_paths
@@ -1,18 +1,5 @@
 #autoload
 
-# This completion function completes all paths given to it, and also tries to
-# offer completions which point to the same file as one of the paths given
-# (relative path when an absolute path is given, and vice versa; when ..'s are
-# present in the word to be completed, and some paths got from symlinks.
-
-# Usage: _canonical_paths [-A var] [-N] [-MJV12nfX] tag desc paths...
-
-# -A, if specified, takes the paths from the array variable specified. Paths can
-# also be specified on the command line as shown above. -N, if specified,
-# prevents canonicalizing the paths given before using them for completion, in
-# case they are already so. `tag' and `desc' arguments are well, obvious :) In
-# addition, the options -M, -J, -V, -1, -2, -n, -F, -X are passed to compadd.
-
 _canonical_paths_pwd() {
   # Get the canonical directory name by changing to it.
   integer chaselinks
diff --git a/Doc/Zsh/compsys.yo b/Doc/Zsh/compsys.yo
index 41864f8..8c7ef0f 100644
--- a/Doc/Zsh/compsys.yo
+++ b/Doc/Zsh/compsys.yo
@@ -2978,6 +2978,21 @@ widgets to find out if the command line hasn't changed since the last
 time completion was tried.  Only then are the tt(_ignored),
 tt(_correct) and tt(_approximate) completers called.
 )
+findex(_canonical_paths)
+item(tt(_canonical_paths) [ tt(-A) var(var) ] [ tt(-N) ] [ tt(-MJV12nfX) ] var(tag) var(descr) [ var(paths) ... ])(
+This completion function completes all paths given to it, and also tries to
+offer completions which point to the same file as one of the paths given
+(relative path when an absolute path is given, and vice versa; when tt(..)'s
+are present in the word to be completed; and some paths got from symlinks).
+
+tt(-A), if specified, takes the paths from the array variable specified. Paths can
+also be specified on the command line as shown above.  tt(-N), if specified,
+prevents canonicalizing the paths given before using them for completion, in
+case they are already so. The options tt(-M), tt(-J), tt(-V), tt(-1), tt(-2),
+tt(-n), tt(-F), tt(-X) are passed to tt(compadd).
+
+See tt(_description) for a description of var(tag) and var(descr).
+)
 findex(_complete)
 item(tt(_complete))(
 This completer generates all possible completions in a context-sensitive