Change syntax for implicit :haddock: autolink. (#484)
authorMatt Renaud <matt@m-renaud.com>
Thu, 11 Jan 2018 17:33:44 +0000 (09:33 -0800)
committerGitHub <noreply@github.com>
Thu, 11 Jan 2018 17:33:44 +0000 (09:33 -0800)
Implicit links must now start with a slash '/'

Before:
  Module        => Not possible
  Module#ident  => current_package/Module#ident

After:
  /Module       => current_package/Module
  /Module#ident => current_package/Module#ident

Previously Module#ident would implicitly link to <package>/Module#ident, but
this prevented implicitly linking to <package>/Module (since its not possible to
differentiate between an explicit Haddock package link or an implicit link
within the current package.

[ci skip]

docs/_extensions/HaddockAutolinker.py
docs/map.rst
docs/sequence.rst
docs/set.rst

index 91f3b65..63335e3 100644 (file)
@@ -30,34 +30,56 @@ def convert_special_chars_to_ascii(func_name):
 
 def parse_haddock_ref_text(text):
     """
-    Parses text of the form pkg-name/Module.Path#func_name into the tuple
-    (package, module, function_name).
+    Parses text of the form pkg-name/Module.Path#ident into the tuple
+    (package, module, ident).
 
     The module and function name are optional, if they are omitted then 'None'
     will be returned in the corresponding tuple element.
 
+    Example inputs:
+      Explicit package references:
+      'pkg' => ('package_name', None, None)
+      'pkg/Module.Name' => ('pkg', 'Module.Name', None)
+      'pkg/Module.Name#ident' => ('pkg', 'Module.Name', 'ident')
+
+      Implicit package references:
+      '/Module.Name' => (None, 'Module.Name', None)
+      '/Module.Name#ident' => (None, 'Module.Name', 'ident')
+
     TODO(m-renaud): Clean this up, there's probably a python parsing library.
     """
 
-    # If there's no '/' then this is either a reference to a package or a local
-    # reference.
+    # If there's no '/' then this is a reference to a package.
+    # A module or identifier reference is invalid here.
     if '/' not in text:
-        if '#' not in text:
+        if '#' in text:
+            print_error('Invalid haddock reference: ' + text)
+            raise Exception('Invalid haddock reference, see error above.')
+            return (None, None, None)
+        else:
             return (text, None, None)
+
+    # Leading '/' means local package reference.
+    # Calling code responsible for determining what "local" means.
+    if 0 == text.find('/'):
+        text = text[1:]
+        if '#' in text:
+            module,ident = text.split('#')
+            return (None, module, ident)
         else:
-            module,func_name = text.split('#')
-            return (None, module, func_name)
+            return (None, text, None)
 
+    # Otherwise, explicit reference.
     pkg_name,rest = text.split('/')
 
-    func_name = None
+    ident = None
     module = None
     if '#' in rest:
-        module,func_name = rest.split('#')
+        module,ident = rest.split('#')
     else:
         module = rest
 
-    return (pkg_name, module, func_name)
+    return (pkg_name, module, ident)
 
 
 
@@ -177,13 +199,13 @@ class HaddockAutolinker:
             Role handler for :haddock:.
             """
 
-            (pkg, module, func_name) = parse_haddock_ref_text(text)
+            (pkg, module, ident) = parse_haddock_ref_text(text)
 
-            # If the pkg isn't set then this is a reference to a function in the current
-            # package.
+            # If the pkg isn't set then this is a local reference to a module
+            # function in the current package.
             if pkg == None:
                 pkg = get_project(inliner)
-            ref = haddock_ref(self.haddock_host, self.haddock_root, pkg, module, func_name)
+            ref = haddock_ref(self.haddock_host, self.haddock_root, pkg, module, ident)
 
             if ref == None:
                 FAIL = '\033[91m'
@@ -198,13 +220,13 @@ class HaddockAutolinker:
             if module == None:
                 link_text = pkg
             else:
-                if func_name == None:
+                if ident == None:
                     link_text = module
                 else:
                     if display_name_only:
-                        link_text = func_name
+                        link_text = ident
                     else:
-                        link_text = module + '#' + func_name
+                        link_text = module + '#' + ident
 
             node = nodes.reference(rawtext, link_text, refuri=ref, **options)
             return [node], []
index dc8e024..168ff44 100644 (file)
@@ -6,8 +6,8 @@ Maps
 Maps (sometimes referred to as dictionaries in other languages) allow you to
 store associations between *unique keys* and *values*. There are three
 implementations provided by the ``containers`` package:
-:haddock:`containers/Data.Map.Strict`, :haddock:`containers/Data.Map.Lazy`, and
-:haddock:`containers/Data.IntMap`. You almost never want the lazy version so use
+:haddock:`/Data.Map.Strict`, :haddock:`/Data.Map.Lazy`, and
+:haddock:`/Data.IntMap`. You almost never want the lazy version so use
 ``Data.Map.Strict``, or if your keys are ``Int`` use ``Data.IntMap``.
 
 ::
@@ -132,7 +132,7 @@ Create an empty map
     Map.empty :: Map k v
     Map.empty = ...
 
-:haddock_short:`Data.Map.Strict#empty` creates a map without any entries.
+:haddock_short:`/Data.Map.Strict#empty` creates a map without any entries.
 
 ::
 
@@ -147,7 +147,7 @@ Create a map with one entry (singleton)
     Map.singleton :: k -> v -> Map k v
     Map.singleton key value = ...
 
-:haddock_short:`Data.Map.Strict#singleton` creates a map with a single
+:haddock_short:`/Data.Map.Strict#singleton` creates a map with a single
 ``(key,value)`` entry in it.
 
 ::
@@ -166,7 +166,7 @@ Create a map from a list
     Map.fromList :: Ord k => [(k, v)] -> Map k v
     Map.fromList xs = ...
 
-:haddock_short:`Data.Map.Strict#fromList` creates a map containing the entries
+:haddock_short:`/Data.Map.Strict#fromList` creates a map containing the entries
 of the list ``xs`` where the keys comes from the first entries of the pairs and
 the values from the second. If the same key appears more than once then the last
 value is taken.
@@ -184,7 +184,7 @@ There's another incredibly useful function for constructing a map from a list::
     Map.fromListWith :: Ord k => (a -> a -> a) -> [(k, a)] -> Map.Map k a
     Map.fromListWith f xs = ...
 
-:haddock_short:`Data.Map.Strict#fromListWith` allows you to build a map from a
+:haddock_short:`/Data.Map.Strict#fromListWith` allows you to build a map from a
 list ``xs`` with repeated keys, where ``f`` is used to "combine" (or "choose")
 values with the same key.
 
@@ -221,9 +221,9 @@ Create a list from a map
    equivalent to ``elems``, although is rarely useful for maps. In general, use
    ``toAscList``.
 
-:haddock_short:`Data.Map.Strict#toAscList`,
-:haddock_short:`Data.Map.Strict#toList`, and
-:haddock_short:`Data.Map.Strict#assocs` returns a list containing the (key,
+:haddock_short:`/Data.Map.Strict#toAscList`,
+:haddock_short:`/Data.Map.Strict#toList`, and
+:haddock_short:`/Data.Map.Strict#assocs` returns a list containing the (key,
 value) pairs in the map ``m`` in *ascending* key order.
 
 ::
@@ -231,7 +231,7 @@ value) pairs in the map ``m`` in *ascending* key order.
     Map.toDescList :: Map k v -> [(k, v)]
     Map.toDescList m = ...
 
-:haddock_short:`Data.Map.Strict#toDescList` returns a list containing the (key,
+:haddock_short:`/Data.Map.Strict#toDescList` returns a list containing the (key,
 value) pairs in the map ``m`` in *descending* key order.
 
 ::
@@ -257,7 +257,7 @@ Lookup an entry in the map (lookup)
     Map.!? :: Ord k => Map k v -> k -> Maybe v
     Map.!? m key = ...
 
-:haddock_short:`Data.Map.Strict#lookup` the value corresponding to the given
+:haddock_short:`/Data.Map.Strict#lookup` the value corresponding to the given
 ``key``, returns ``Nothing`` if the key is not present; the ``!?`` operator
 (*since 0.5.10*) is a flipped version of ``lookup`` and can often be imported
 unqualified.
@@ -304,7 +304,7 @@ Check if a map is empty
     Map.null :: Map k v -> Bool
     Map.null m = ...
 
-:haddock_short:`Data.Map.Strict#null` returns ``True`` if the map ``m`` is
+:haddock_short:`/Data.Map.Strict#null` returns ``True`` if the map ``m`` is
 empty and ``False`` otherwise.
 
 ::
@@ -323,7 +323,7 @@ The number of entries in a map
     Map.size :: Map k v -> Int
     Map.size m = ...
 
-:haddock_short:`Data.Map.Strict#size` returns the number of entries in the map
+:haddock_short:`/Data.Map.Strict#size` returns the number of entries in the map
 ``m``.
 
 ::
@@ -345,8 +345,8 @@ Find the minimum/maximum
     Map.lookupMin m = ...
     Map.lookupMax m = ...
 
-:haddock_short:`Data.Map.Strict#lookupMin` and
-:haddock_short:`Data.Map.Strict#lookupMax` respectively return the
+:haddock_short:`/Data.Map.Strict#lookupMin` and
+:haddock_short:`/Data.Map.Strict#lookupMax` respectively return the
 minimum or maximum element of the map ``m``, or ``Nothing`` if the map is empty.
 
 ::
@@ -375,7 +375,7 @@ Adding a new entry to a map
     Map.insert :: Ord k => k -> v -> Map k v -> Map k v
     Map.insert key value m = ...
 
-:haddock_short:`Data.Map.Strict#insert` adds the ``value`` into the map ``m``
+:haddock_short:`/Data.Map.Strict#insert` adds the ``value`` into the map ``m``
 with the given ``key``, replacing the existing value if the key already exists.
 
 ::
@@ -398,7 +398,7 @@ Removing an entry from a map
     Map.delete :: Ord k => k -> Map k v -> Map k v
     Map.delete key m = ...
 
-:haddock_short:`Data.Map.Strict#delete` removes the entry with the specified
+:haddock_short:`/Data.Map.Strict#delete` removes the entry with the specified
 ``key`` from the map ``m``.  If the key doesn't exist it leaves the map
 unchanged.
 
@@ -418,7 +418,7 @@ Filtering map entries
     Map.filterWithKey :: (k -> v -> Bool) -> Map k v -> Map k v
     Map.filterWithKey predicate m = ...
 
-:haddock_short:`Data.Map.Strict#filterWithKey` produces a map consisting of all
+:haddock_short:`/Data.Map.Strict#filterWithKey` produces a map consisting of all
 entries of ``m`` for which the ``predicate`` returns ``True``.
 
 ::
@@ -436,7 +436,7 @@ Modifying a map entry
     Map.adjust :: Ord k => (v -> v) -> k -> Map k v -> Map k v
     Map.adjust f key m = ...
 
-:haddock_short:`Data.Map.Strict#abjust` applies the value transformation
+:haddock_short:`/Data.Map.Strict#abjust` applies the value transformation
 function ``f`` to the entry with given ``key``. If no entry for that key exists
 then the map is left unchanged.
 
@@ -494,11 +494,11 @@ Modifying all map entries (mapping and traversing)
     Map.mapWithKey g m = ...
 
 
-:haddock_short:`Data.Map.Strict#map` creates a new map by applying the
+:haddock_short:`/Data.Map.Strict#map` creates a new map by applying the
 transformation function ``f`` to each entries value. This is how `Functor
 <https://wiki.haskell.org/Typeclassopedia#Functor>`_ is defined for maps.
 
-:haddock_short:`Data.Map.Strict#mapWithKey` does the same as ``map`` but gives
+:haddock_short:`/Data.Map.Strict#mapWithKey` does the same as ``map`` but gives
 you access to the key in the transformation function ``g``.
 
 ::
@@ -523,7 +523,7 @@ each entry in the map.
     Map.traverseWithKey :: Applicative t => (k -> a -> t b) -> Map.Map k a -> t (Map.Map k b)
     Map.traverseWithKey f m = ...
 
-:haddock_short:`Data.Map.Strict#traverseWithKey` maps each element of the map
+:haddock_short:`/Data.Map.Strict#traverseWithKey` maps each element of the map
 ``m`` to an *action* that produces a result of type ``b``. The actions are
 performed and the values of the map are replaced with the results from the
 function. You can think of this as a ``map`` with affects.
@@ -555,7 +555,7 @@ Union
     Map.unionWith :: Ord k => (v -> v -> v) -> Map k v -> Map k v -> Map k v
     Map.unionWith f l r = ...
 
-:haddock_short:`Data.Map.Strict#union` returns a map containing all entries that
+:haddock_short:`/Data.Map.Strict#union` returns a map containing all entries that
 are keyed in either of the two maps. If the same key appears in both maps, the
 value is determined by calling ``f`` passing in the left and right value (`set
 union <https://en.wikipedia.org/wiki/Union_(set_theory)>`_).
@@ -582,7 +582,7 @@ Intersection
     Map.intersectionWith :: Ord k => (v -> v -> v) -> Map k v -> Map k v -> Map k v
     Map.intersectionWith f l r = ...
 
-:haddock_short:`Data.Map.Strict#intersection` returns a map containing all
+:haddock_short:`/Data.Map.Strict#intersection` returns a map containing all
 entries that have a key in both maps ``l`` and ``r``. The value in the returned
 map is determined by calling ``f`` on the values from the left and right map
 (`set intersection <https://en.wikipedia.org/wiki/Intersection_(set_theory)>`_).
@@ -605,7 +605,7 @@ Difference
     Map.difference :: Ord k => Map k v -> Map k v -> Map k v
     Map.difference l r = ...
 
-:haddock_short:`Data.Map.Strict#difference` returns a map containing all entries
+:haddock_short:`/Data.Map.Strict#difference` returns a map containing all entries
 that have a key in the ``l`` map but not the ``r`` map (`set difference/relative
 complement
 <https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement>`_).
@@ -629,7 +629,7 @@ use.
 
 .. TIP::
    If you are writing custom serialization code use
-   :haddock_short:`Data.Map.Strict#fromDistinctAscList` (see
+   :haddock_short:`/Data.Map.Strict#fromDistinctAscList` (see
    `#405 <https://github.com/haskell/containers/issues/405>`_ for more info).
 
 
@@ -646,5 +646,5 @@ Looking for more?
 
 Didn't find what you're looking for? This tutorial only covered the most common
 map functions, for a full list of functions see the
-:haddock_short:`Data.Map.Strict#Map` and
-:haddock_short:`Data.IntMap.Strict#IntMap` API documentation.
+:haddock_short:`/Data.Map.Strict#Map` and
+:haddock_short:`/Data.IntMap.Strict#IntMap` API documentation.
index cb0b83b..7b32455 100644 (file)
@@ -5,8 +5,8 @@ Sequences
 
 Sequences allow you to store a finite number of sequential elements, providing
 fast access to both ends of the sequence as well as efficient concatenation. The
-``containers`` package provides the :haddock:`containers/Data.Sequence` module
-which defines the ``Seq`` data type.
+``containers`` package provides the :haddock:`/Data.Sequence` module which
+defines the ``Seq`` data type.
 
 
 Short Example
@@ -108,7 +108,7 @@ Create an empty sequence
     Seq.empty :: Seq a
     Seq.empty = ...
 
-:haddock_short:`Data.Sequence#empty` creates a sequence with zero elements.
+:haddock_short:`/Data.Sequence#empty` creates a sequence with zero elements.
 
 ::
 
@@ -124,7 +124,7 @@ Create a sequence with one element (singleton)
     Seq.singleton :: a -> Seq a
     Seq.singleton x = ...
 
-:haddock_short:`Data.Sequence#singleton` creates a sequence with the single
+:haddock_short:`/Data.Sequence#singleton` creates a sequence with the single
 element ``x`` in it.
 
 ::
@@ -143,7 +143,7 @@ Create a sequence with the same element repeated
     Seq.replicate :: Int -> a -> Seq a
     Seq.replicate n x = ...
 
-:haddock_short:`Data.Sequence#replicate` creates a sequence with same element
+:haddock_short:`/Data.Sequence#replicate` creates a sequence with same element
 ``x`` repeated ``n`` times.
 
 ::
@@ -162,7 +162,7 @@ Create a sequence from a list
     Seq.fromList :: [a] -> Seq a
     Seq.FromList xs = ...
 
-:haddock_short:`Data.Sequence#fromList` creates a sequence containing the
+:haddock_short:`/Data.Sequence#fromList` creates a sequence containing the
 elements of the list ``xs``. Sequences allow duplicate so all elements will be
 included in the order given.
 
@@ -265,7 +265,7 @@ Check if a sequence is empty
     Seq.null :: Seq a -> Bool
     Seq.null xs = ...
 
-:haddock_short:`Data.Sequence#null` returns ``True`` if the sequence ``xs`` is
+:haddock_short:`/Data.Sequence#null` returns ``True`` if the sequence ``xs`` is
 empty, and ``False`` otherwise.
 
 ::
@@ -284,7 +284,7 @@ The length/size of a sequence
     Seq.length :: Seq a -> Int
     Seq.length xs = ...
 
-:haddock_short:`Data.Sequence#length` returns the length of the sequence ``xs``.
+:haddock_short:`/Data.Sequence#length` returns the length of the sequence ``xs``.
 
 ::
 
@@ -305,8 +305,8 @@ The element at a given index
     Seq.!? :: Seq a -> Int -> Maybe a
     xs !? n = ...
 
-:haddock_short:`Data.Sequence#lookup` returns the element at the position ``n``,
-or ``Nothing`` if the index is out of bounds. :haddock_short:`Data.Sequence#!?`
+:haddock_short:`/Data.Sequence#lookup` returns the element at the position ``n``,
+or ``Nothing`` if the index is out of bounds. :haddock_short:`/Data.Sequence#!?`
 is simply a flipped version of ``lookup``.
 
 .. NOTE::
@@ -319,7 +319,7 @@ is simply a flipped version of ``lookup``.
     Seq.index :: Seq a -> Int -> a
     Seq.index xs n = ...
 
-:haddock_short:`Data.Sequence#index` returns the element at the given
+:haddock_short:`/Data.Sequence#index` returns the element at the given
 position. It throws a runtime error if the index is out of bounds.
 
 .. TIP::
@@ -362,7 +362,7 @@ Inserting an element
     Seq.insertAt :: Int -> a -> Seq a -> Seq a
     Seq.insertAt i x xs = ...
 
-:haddock_short:`Data.Sequence#insertAt` inserts ``x`` into ``xs`` at the index
+:haddock_short:`/Data.Sequence#insertAt` inserts ``x`` into ``xs`` at the index
 ``i``, shifting the rest of the sequence over. If ``i`` is out of range then
 ``x`` will be inserted at the beginning or the end of the sequence as
 appropriate.
@@ -388,7 +388,7 @@ Delete an element
     Seq.deleteAt :: Int -> Seq a -> Seq a
     Seq.deleteAt i xs = ...
 
-:haddock_short:`Data.Sequence#deleteAt` removes the element of the sequence at
+:haddock_short:`/Data.Sequence#deleteAt` removes the element of the sequence at
 index ``i``. If the index is out of bounds then the original sequence is
 returned.
 
@@ -408,7 +408,7 @@ Replace an element
     Seq.update :: Int -> a -> Seq a -> Seq a
     Seq.update i x xs = ...
 
-:haddock_short:`Data.Sequence#update` replaces the element at position ``i`` in
+:haddock_short:`/Data.Sequence#update` replaces the element at position ``i`` in
 the sequence with ``x``. If the index is out of bounds then the original
 sequence is returned.
 
@@ -430,7 +430,7 @@ Adjust/modify an element
     adjust' :: forall a. (a -> a) -> Int -> Seq a -> Seq a
     adjust' f i xs = ...
 
-:haddock_short:`Data.Sequence#adjust'` updates the element at position ``i`` in
+:haddock_short:`/Data.Sequence#adjust'` updates the element at position ``i`` in
 the sequence by applying the function ``f`` to the existing element. If the
 index is out of bounds then the original sequence is returned.
 
@@ -445,7 +445,7 @@ index is out of bounds then the original sequence is returned.
 .. NOTE::
    If you're using an older version of containers which only has ``adjust``, be
    careful because it can lead to poor performance and space leaks (see
-   :haddock_short:`Data.Sequence#adjust` docs).
+   :haddock_short:`/Data.Sequence#adjust` docs).
 
 Modifying all elements
 """"""""""""""""""""""
@@ -458,12 +458,12 @@ Modifying all elements
     Seq.mapWithIndex :: (Int -> a -> b) -> Seq a -> Seq b
     Seq.mapWithIndex f xs = ...
 
-:haddock_short:`Data.Sequence#fmap` transform each element of the sequence with
+:haddock_short:`/Data.Sequence#fmap` transform each element of the sequence with
 the function ``f``. ``fmap`` is provided by the `Functor
 <https://wiki.haskell.org/Typeclassopedia#Functor>`_ instance for sequences and
 can also be written infix using the ``<$>`` operator.
 
-:haddock_short:`Data.Sequence#mapWithIndex` allows you to do a similar
+:haddock_short:`/Data.Sequence#mapWithIndex` allows you to do a similar
 transformation but gives you the index that each element is at.
 
 ::
@@ -491,7 +491,7 @@ Sorting
     Seq.sort :: Ord a => Seq a -> Seq a
     Seq.sort xs = ...
 
-:haddock_short:`Data.Sequence#sort` the sequence ``xs`` using the ``Ord``
+:haddock_short:`/Data.Sequence#sort` the sequence ``xs`` using the ``Ord``
 instance.
 
 ::
@@ -511,7 +511,7 @@ Take
     Seq.take :: Int -> Seq a -> Seq a
     Seq.take n xs = ...
 
-:haddock_short:`Data.Sequence#take` returns the first ``n`` elements of the
+:haddock_short:`/Data.Sequence#take` returns the first ``n`` elements of the
 sequence ``xs``. If the length of ``xs`` is less than ``n`` then all elements
 are returned.
 
@@ -534,7 +534,7 @@ Drop
     Seq.drop :: Int -> Seq a -> Seq a
     Seq.drop n xs = ...
 
-:haddock_short:`Data.Sequence#drop` the first ``n`` elements of the sequence
+:haddock_short:`/Data.Sequence#drop` the first ``n`` elements of the sequence
 ``xs``. If the length of ``xs`` is less than ``n`` then an empty sequence is
 returned.
 
@@ -557,7 +557,7 @@ Chunks
     Seq.chunksOf :: Int -> Seq a -> Seq (Seq a)
     Seq.chunksOf k xs = ...
 
-:haddock_short:`Data.Sequence#chunksOf` splits the sequence ``xs`` into chunks
+:haddock_short:`/Data.Sequence#chunksOf` splits the sequence ``xs`` into chunks
 of size ``k``. If the length of the sequence is not evenly divisible by ``k``
 then the last chunk will have less than ``k`` elements.
 
@@ -592,10 +592,10 @@ Folding
     Seq.foldrWithIndex :: (Int -> a -> b -> b) -> b -> Seq a -> b
     Seq.foldrWithIndex f init xs = ...
 
-:haddock_short:`Data.Sequence#foldr` collapses the sequence into a summary value
-by repeatedly applying ``f``. ``foldr`` is provided by the `Foldable
+:haddock_short:`/Data.Sequence#foldr` collapses the sequence into a summary
+value by repeatedly applying ``f``. ``foldr`` is provided by the `Foldable
 <https://wiki.haskell.org/Typeclassopedia#Foldable>`_ instance for
-sequences. :haddock_short:`Data.Sequence#foldWithIndex` gives you access to the
+sequences. :haddock_short:`/Data.Sequence#foldWithIndex` gives you access to the
 position in the sequence when transforming each element.
 
 ::
@@ -633,4 +633,4 @@ Looking for more?
 
 Didn't find what you're looking for? This tutorial only covered the most common
 sequence functions, for a full list of functions see the
-:haddock:`containers/Data.Sequence` API documentation.
+:haddock:`/Data.Sequence` API documentation.
index c4470d8..09ba5ec 100644 (file)
@@ -5,9 +5,8 @@ Sets
 
 Sets allow you to store *unique*, *ordered* elements, providing efficient
 insertion, lookups, deletions, and set operations. There are two implementations
-provided by the ``containers`` package: :haddock:`containers/Data.Set` and
-:haddock:`containers/Data.IntSet`. Use ``IntSet`` if you are storing,
-well... ``Int`` s.
+provided by the ``containers`` package: :haddock:`/Data.Set` and
+:haddock:`/Data.IntSet`. Use ``IntSet`` if you are storing, well... ``Int`` s.
 
 ::
 
@@ -124,7 +123,7 @@ Create an empty set
     Set.empty :: Set a
     Set.empty = ...
 
-:haddock_short:`Data.Set#empty` creates a set with zero elements.
+:haddock_short:`/Data.Set#empty` creates a set with zero elements.
 
 ::
 
@@ -139,7 +138,7 @@ Create a set with one element (singleton)
     Set.singleton :: a -> Set a
     Set.singleton x = ...
 
-:haddock_short:`Data.Set#singleton` creates a set with a single element ``x`` in
+:haddock_short:`/Data.Set#singleton` creates a set with a single element ``x`` in
 it.
 
 ::
@@ -158,7 +157,7 @@ Create a set from a list
     Set.fromList :: Ord a => [a] -> Set a
     Set.fromList xs = ...
 
-:haddock_short:`Data.Set#fromList` creates a set containing the elements of the
+:haddock_short:`/Data.Set#fromList` creates a set containing the elements of the
 list ``xs``. Since sets don't contain duplicates, if there are repeated elements
 in the list they will only appear once.
 
@@ -178,9 +177,9 @@ Create a list from a set
     Set.toAscList, Set.toList, Set.elems :: Set a -> [a]
     Set.toAscList s = ...
 
-:haddock_short:`Data.Set#toAscList`, :haddock_short:`Data.Set#toList`, and
-:haddock_short:`Data.Set#elems` return a list containing the elements of the set
-:haddock_short:``s`` in *ascending* order.
+:haddock_short:`/Data.Set#toAscList`, :haddock_short:`/Data.Set#toList`, and
+:haddock_short:`/Data.Set#elems` return a list containing the elements of the set
+:haddock_short:`/`s`` in *ascending* order.
 
 .. NOTE::
    These all do the same thing; use ``toAscList`` because its name indicates the
@@ -191,7 +190,7 @@ Create a list from a set
     Set.toDescList :: Set a -> [a]
     Set.toDescList s = ...
 
-:haddock_short:`Data.Set#toDescList` returns a list containing the elements of
+:haddock_short:`/Data.Set#toDescList` returns a list containing the elements of
 the set ``s`` in *descending* order.
 
 ::
@@ -214,7 +213,7 @@ Check if an element is in a set (member)
     Set.member :: Ord a => a -> Set a -> Bool
     Set.member x s = ...
 
-:haddock_short:`Data.Set#member` returns ``True`` if the element ``x`` is in the
+:haddock_short:`/Data.Set#member` returns ``True`` if the element ``x`` is in the
 set ``s``, ``False`` otherwise.
 
 ::
@@ -233,7 +232,7 @@ Check if a set is empty
     Set.null :: Set a -> Bool
     Set.null s = ...
 
-:haddock_short:`Data.Set#null` returns ``True`` if the set ``s`` is empty,
+:haddock_short:`/Data.Set#null` returns ``True`` if the set ``s`` is empty,
 ``False`` otherwise.
 
 ::
@@ -253,7 +252,7 @@ The number of elements in a set
     Set.size :: Set a -> Int
     Set.size s = ...
 
-:haddock_short:`Data.Set#size` returns the number of elements in the set ``s``.
+:haddock_short:`/Data.Set#size` returns the number of elements in the set ``s``.
 
 ::
 
@@ -274,7 +273,7 @@ Find the minimum/maximum element in a set
    lookupMin s = ...
    lookupMax s = ...
 
-:haddock_short:`Data.Set#lookupMin` returns the minimum, or maximum
+:haddock_short:`/Data.Set#lookupMin` returns the minimum, or maximum
 respectively, element of the set ``s``, or ``Nothing`` if the set is empty.
 
 ::
@@ -304,7 +303,7 @@ Adding a new element to a set
     Set.insert :: Ord a => a -> Set a -> Set a
     Set.insert x s = ...
 
-:haddock_short:`Data.Set#insert` places the element ``x`` into the set ``s``,
+:haddock_short:`/Data.Set#insert` places the element ``x`` into the set ``s``,
 replacing an existing equal element if it already exists.
 
 ::
@@ -323,7 +322,7 @@ Removing an element from a set
     Set.delete :: Ord a => a -> Set a -> Set a
     Set.delete x s = ...
 
-:haddock_short:`Data.Set#delete` the element ``x`` from the set ``s``. If it’s
+:haddock_short:`/Data.Set#delete` the element ``x`` from the set ``s``. If it’s
 not a member it leaves the set unchanged.
 
 ::
@@ -339,7 +338,7 @@ Filtering elements from a set
     Set.filter :: (a -> Bool) -> Set a -> Set a
     Set.filter predicate s = ...
 
-:haddock_short:`Data.Set#filter` produces a set consisting of all elements of
+:haddock_short:`/Data.Set#filter` produces a set consisting of all elements of
 ``s`` for which the `predicate`` returns ``True``.
 
 ::
@@ -359,7 +358,7 @@ Union
     Set.union :: Ord a => Set a -> Set a -> Set a
     Set.union l r = ...
 
-:haddock_short:`Data.Set#union` returns a set containing all elements that are
+:haddock_short:`/Data.Set#union` returns a set containing all elements that are
 in either of the two sets ``l`` or ``r`` (`set union
 <https://en.wikipedia.org/wiki/Union_(set_theory)>`_).
 
@@ -379,7 +378,7 @@ Intersection
     Set.intersection :: Ord a => Set a -> Set a -> Set a
     Set.intersection l r = ...
 
-:haddock_short:`Data.Set#intersection` returns a set the elements that are in
+:haddock_short:`/Data.Set#intersection` returns a set the elements that are in
 both sets ``l`` and ``r`` (`set intersection
 <https://en.wikipedia.org/wiki/Intersection_(set_theory)>`_).
 
@@ -402,7 +401,7 @@ Difference
     Set.difference :: Ord a => Set a -> Set a -> Set a
     Set.difference l r = ...
 
-:haddock_short:`Data.Set#difference` returns a set containing the elements that
+:haddock_short:`/Data.Set#difference` returns a set containing the elements that
 are in the first set ``l`` but not the second set ``r`` (`set
 difference/relative compliment
 <https://en.wikipedia.org/wiki/Complement_(set_theory)#Relative_complement>`_).
@@ -426,7 +425,7 @@ Subset
     Set.isSubsetOf :: Ord a => Set a -> Set a -> Bool
     Set.isSubsetOf l r = ...
 
-:haddock_short:`Data.Set#isSubsetOf` returns ``True`` if all elements in the
+:haddock_short:`/Data.Set#isSubsetOf` returns ``True`` if all elements in the
 first set ``l`` are also in the second set ``r`` (`subset
 <https://en.wikipedia.org/wiki/Subset>`_).
 
@@ -460,7 +459,7 @@ use.
 
 .. TIP::
    If you are writing custom serialization code use
-   :haddock_short:`Data.Set#fromDistinctAscList` (see
+   :haddock_short:`/Data.Set#fromDistinctAscList` (see
    `#405 <https://github.com/haskell/containers/issues/405>`_ for more info).
 
 Performance
@@ -476,5 +475,5 @@ Looking for more?
 
 Didn't find what you're looking for? This tutorial only covered the most common
 set functions, for a full list of functions see the
-:haddock_short:`Data.Set#Set` and :haddock_short:`Data.IntSet#IntSet` API
+:haddock_short:`/Data.Set#Set` and :haddock_short:`/Data.IntSet#IntSet` API
 documentation.