discovery: fix docstring of `outgoing` class

discovery: fix docstring of `outgoing` class

Also, introduce a more correct name `ancestorsof` for what was named
`missingheads` before. For now, we just forward `ancestorsof` to `missingheads`
until all users are changed.

There were some mistakes in the old docstring / name:

* `missingheads` (new name: `ancestorsof`) contains the revs whose ancestors
  are included in the outgoing operation. It may contain non-head revs and revs
  which are already on the remote, so the name "missingheads" is wrong in two
  ways.
* `missing` contains only ancestors of `missingheads`, so not *all nodes*
  present in local but not in remote.
* `common` might not contain all common revs, e.g. not some that are not an
  ancestor of `missingheads`.

It seems like the misleading name have fostered an actual bug (issue6372),
where `outgoing.missingheads` was used assuming that it contains the heads of
the missing changesets.

--- a/mercurial/discovery.py	Wed Jul 15 09:51:11 2020 +0200
+++ b/mercurial/discovery.py	Wed Jul 15 11:38:54 2020 +0200
@@ -75,18 +75,28 @@
 
 
 class outgoing(object):
-    '''Represents the set of nodes present in a local repo but not in a
-    (possibly) remote one.
+    '''Represents the result of a findcommonoutgoing() call.
 
     Members:
 
-      missing is a list of all nodes present in local but not in remote.
-      common is a list of all nodes shared between the two repos.
-      excluded is the list of missing changeset that shouldn't be sent remotely.
-      missingheads is the list of heads of missing.
+      ancestorsof is a list of the nodes whose ancestors are included in the
+      outgoing operation.
+
+      missing is a list of those ancestors of ancestorsof that are present in
+      local but not in remote.
+
+      common is a set containing revs common between the local and the remote
+      repository (at least all of those that are ancestors of ancestorsof).
+
       commonheads is the list of heads of common.
 
-    The sets are computed on demand from the heads, unless provided upfront
+      excluded is the list of missing changeset that shouldn't be sent
+      remotely.
+
+      missingheads is an alias to ancestorsof, but the name is wrong and it
+      will be removed
+
+    Some members are computed on demand from the heads, unless provided upfront
     by discovery.'''
 
     def __init__(
@@ -135,6 +145,10 @@
             self._computecommonmissing()
         return self._missing
 
+    @property
+    def ancestorsof(self):
+        return self.missingheads
+
 
 def findcommonoutgoing(
     repo, other, onlyheads=None, force=False, commoninc=None, portable=False