Merge pull request #2834 from shati-patel/2160-prep-ql-language

Minor update to QL language topics

Author: jf205

docs/language/ql-handbook/index.rst

@@ -21,7 +21,6 @@ Table of contents
 *****************
 
 .. toctree::
-   :numbered: 3
    :maxdepth: 3
 
    predicates
@@ -42,4 +41,4 @@ Index and search
 ****************
 
 * :ref:`genindex`
-* :ref:`search`
+* :ref:`search`

docs/language/ql-handbook/lexical-syntax.rst

@@ -19,7 +19,7 @@ All standard one-line and multiline comments, as described in the `QL language s
 compiler and are only visible in the source code.
 You can also write another kind of comment, namely **QLDoc comments**. These comments describe
 QL entities and are displayed as pop-up information in QL editors. For information about QLDoc
-comments, see the `QLDoc specification <https://help.semmle.com/QL/ql-spec/qldoc.html>`_.
+comments, see the `QLDoc comment specification <https://help.semmle.com/QL/ql-spec/qldoc.html>`_.
 
 The following example uses these three different kinds of comments::
 

docs/language/ql-spec/index.rst

@@ -6,7 +6,7 @@ QL specifications
 
 For a formal specification of the QL language, including a description of syntax, terminology, and other technical details, please consult the QL language specification.
 
-For information on the terminology and syntax used in QLDoc comments, please consult the QLDoc specification.
+For information on the terminology and syntax used in QLDoc comments, please consult the QLDoc comment specification.
 
 .. toctree::
    :maxdepth: 2

docs/language/ql-spec/qldoc.rst

@@ -1,7 +1,12 @@
-QLDoc specification
-===================
+QLDoc comment specification
+===========================
 
-This document is a specification for QLDoc comments in QL source files.
+This document is a formal specification for QLDoc comments.
+
+About QLDoc comments
+--------------------
+
+You can provide documentation for a QL entity by adding a QLDoc comment in the source file. The QLDoc comment is displayed as pop-up information in QL editors, for example when you hover over a predicate name.
 
 Notation
 --------
@@ -36,7 +41,7 @@ Content
 
 The content of a QLDoc comment is interpreted as standard Markdown, with the following extensions:
 
--  Fenced code blocks using \`s.
+-  Fenced code blocks using backticks.
 -  Automatic interpretation of links and email addresses.
 -  Use of appropriate characters for ellipses, dashes, apostrophes, and quotes.