Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 2bda26b

Browse files
author
alexet
committed
QLSpec: Make qldoc part of the language.
We have treated it this way for a while internally and it corrects for some minor deviations from the spec.
1 parent e87fd86 commit 2bda26b

2 files changed

Lines changed: 74 additions & 70 deletions

File tree

‎docs/codeql/ql-language-reference/ql-language-specification.rst‎

Lines changed: 74 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -446,7 +446,7 @@ A one-line comment is two slash characters (``/``, U+002F) followed by any seque
446446

447447
// This is a comment
448448

449-
A multiline comment is a *comment start*, followed by a *comment body*, followed by a *comment end*. A comment start is a slash (``/``, U+002F) followed by an asterisk (``*``, U+002A), and a comment end is an asterisk followed by a slash. A comment body is any sequence of characters that does not include a comment end. Here is an example multiline comment:
449+
A multiline comment is a *comment start*, followed by a *comment body*, followed by a *comment end*. A comment start is a slash (``/``, U+002F) followed by an asterisk (``*``, U+002A), and a comment end is an asterisk followed by a slash. A comment body is any sequence of characters that does not include a comment end and does not start with an asterisk. Here is an example multiline comment:
450450

451451
::
452452

@@ -456,6 +456,21 @@ A multiline comment is a *comment start*, followed by a *comment body*, followed
456456
It had a multiline comment.
457457
*/
458458

459+
QLDoc (qldoc)
460+
~~~~~~~~
461+
462+
A QLDoc comment is a *qldoc comment start*, followed by a *comment body*, followed by a *qldoc comment end*. A comment start is a slash (``/``, U+002F) followed by two asterisks (``*``, U+002A), and a qldoc comment end is an asterisk followed by a slash. A qldoc comment body is any sequence of characters that does not include a comment end. Here is an example qldoc comment:
463+
464+
::
465+
466+
/**
467+
It was the best of code.
468+
It was the worst of code.
469+
It had a qldoc comment.
470+
*/
471+
472+
The ‘content’ of a QLDoc comment is the comment body of the comment, omitting the initial /**, the trailing */, and the leading whitespace followed by * on each internal line.
473+
459474
Keywords
460475
~~~~~~~~
461476

@@ -738,6 +753,49 @@ A predicate may have several different binding sets, which can be stated by usin
738753
| ``bindingset`` | | yes | yes | yes | | | | |
739754
+----------------+---------+------------+-------------------+-----------------------+---------+--------+---------+---------+
740755

756+
QLDoc
757+
-----
758+
759+
QLDoc is used for documenting ql entities and bindings. QLDoc that is used as part of the
760+
declaration is said to be declared.
761+
762+
Ambiguous QLDoc
763+
~~~~~~~~~~~
764+
765+
If QLDoc could be parsed as part a file module or as part of the first declaration in the file then
766+
it is parsed as part of the first declaration.
767+
768+
Inheriting QLDoc
769+
~~~~~~~~~~~
770+
771+
If no qldoc is provided then in may be inherited.
772+
773+
In the case of an alias then it may be inherited from the right-hand-side of the alias.
774+
775+
In the case of a member predicate we collect all member predicates that it overrides with declared QLDoc. Then if there is a member predicate in that collection that
776+
that overrides every other member predicate in that collection then the QLDoc of that field is used as the QLDoc.
777+
778+
In the case of a field we collect all fields that it overrides with declared QLDoc. Then if there is a field in that collection that
779+
that overrides every other field in that collection then its QLDoc of that field used as the QLDoc.
780+
781+
Content
782+
~~~~~~~
783+
784+
The content of a QLDoc comment is interpreted as standard Markdown, with the following extensions:
785+
786+
- Fenced code blocks using backticks.
787+
- Automatic interpretation of links and email addresses.
788+
- Use of appropriate characters for ellipses, dashes, apostrophes, and quotes.
789+
790+
The content of a QLDoc comment may contain metadata tags as follows:
791+
792+
The tag begins with any number of whitespace characters, followed by an '@' sign. At this point there may be any number of non-whitespace characters, which form the key of the tag. Then, a single whitespace character which separates the key from the value. The value of the tag is formed by the remainder of the line, and any subsequent lines until another '@' tag is seen, or the end of the content is reached. Any sequence of consecutive whitespace characters in the value are replaced by a single space.
793+
794+
Metadata
795+
~~~~~~~~
796+
797+
If the query file starts with whitespace followed by a qldoc comment then the tags from that qldoc comment form the query metadata.
798+
741799
Top-level entities
742800
------------------
743801

@@ -750,7 +808,7 @@ A *predicate* is declared as a sequence of annotations, a head, and an optional
750808

751809
::
752810

753-
predicate ::= annotations head optbody
811+
predicate ::= qldoc? annotations head optbody
754812

755813
A predicate definition adds a mapping from the predicate name and arity to the predicate declaration to the current module's declared predicate environment.
756814

@@ -785,7 +843,7 @@ A class definition has the following syntax:
785843

786844
::
787845

788-
class ::= annotations "class" classname "extends" type ("," type)* "{" member* "}"
846+
class ::= qldoc? annotations "class" classname "extends" type ("," type)* "{" member* "}"
789847

790848
The identifier following the ``class`` keyword is the name of the class.
791849

@@ -824,8 +882,8 @@ Each member of a class is either a *character*, a predicate, or a field:
824882
::
825883

826884
member ::= character | predicate | field
827-
character ::= annotations classname "(" ")" "{" formula "}"
828-
field ::= annotations var_decl ";"
885+
character ::= qldoc? annotations classname "(" ")" "{" formula "}"
886+
field ::= qldoc? annotations var_decl ";"
829887

830888
Characters
831889
^^^^^^^^^^
@@ -1476,9 +1534,9 @@ Aliases define new names for existing QL entities.
14761534

14771535
::
14781536

1479-
alias ::= annotations "predicate" literalId "=" predicateRef "/" int ";"
1480-
| annotations "class" classname "=" type ";"
1481-
| annotations "module" modulename "=" moduleId ";"
1537+
alias ::= qldoc? annotations "predicate" literalId "=" predicateRef "/" int ";"
1538+
| qldoc? annotations "class" classname "=" type ";"
1539+
| qldoc? annotations "module" modulename "=" moduleId ";"
14821540
14831541

14841542
An alias introduces a binding from the new name to the entity referred to by the right-hand side in the current module's declared predicate, type, or module environment respectively.
@@ -1896,7 +1954,7 @@ The complete grammar for QL is as follows:
18961954

18971955
::
18981956

1899-
ql ::= moduleBody
1957+
ql ::= qldoc? moduleBody
19001958

19011959
module ::= annotation* "module" modulename "{" moduleBody "}"
19021960

@@ -1919,7 +1977,7 @@ The complete grammar for QL is as follows:
19191977

19201978
orderby ::= simpleId ("asc" | "desc")?
19211979

1922-
predicate ::= annotations head optbody
1980+
predicate ::= qldoc? annotations head optbody
19231981

19241982
annotations ::= annotation*
19251983

@@ -1946,23 +2004,23 @@ The complete grammar for QL is as follows:
19462004
| "{" formula "}"
19472005
| "=" literalId "(" (predicateRef "/" int ("," predicateRef "/" int)*)? ")" "(" (exprs)? ")"
19482006

1949-
class ::= annotations "class" classname "extends" type ("," type)* "{" member* "}"
2007+
class ::= qldoc? annotations "class" classname "extends" type ("," type)* "{" member* "}"
19502008

19512009
member ::= character | predicate | field
19522010

1953-
character ::= annotations classname "(" ")" "{" formula "}"
2011+
character ::= qldoc? annotations classname "(" ")" "{" formula "}"
19542012

1955-
field ::= annotations var_decl ";"
2013+
field ::= qldoc? annotations var_decl ";"
19562014

19572015
moduleId ::= simpleId | moduleId "::" simpleId
19582016

19592017
type ::= (moduleId "::")? classname | dbasetype | "boolean" | "date" | "float" | "int" | "string"
19602018

19612019
exprs ::= expr ("," expr)*
19622020

1963-
alias := annotations "predicate" literalId "=" predicateRef "/" int ";"
1964-
| annotations "class" classname "=" type ";"
1965-
| annotations "module" modulename "=" moduleId ";"
2021+
alias := qldoc? annotations "predicate" literalId "=" predicateRef "/" int ";"
2022+
| qldoc? annotations "class" classname "=" type ";"
2023+
| qldoc? annotations "module" modulename "=" moduleId ";"
19662024
19672025
var_decls ::= var_decl ("," var_decl)*
19682026

‎docs/codeql/ql-language-reference/qldoc-comment-specification.rst‎

Lines changed: 0 additions & 54 deletions
This file was deleted.

0 commit comments

Comments
 (0)