Learning CodeQL docs: update links to match GitHub docs style #4046
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Marcono1234
reviewed
Aug 11, 2020
There was a problem hiding this comment.
Hopefully this review is helpful, though I am not really familiar with ReST.
Is it intended that some (but not all) closing double quotes have two space characters behind them, e.g.:
https://github.com/github/codeql/pull/4046/files/0ff10c319da2e2865115fc11a88777bf26416e81#diff-684eb72498d756bc13f287e5728e22cdR141
| and value.getValue() != "" | ||
| and value.getValue() != " |
There was a problem hiding this comment.
Was this changed by accident?
| @@ -25,7 +25,7 @@ When you have selected a presentation, use |arrow-r| and |arrow-l| to navigate b | |||
| Press **p** to view the additional notes on slides that have an information icon |info| in the top right corner, and press **f** to enter full-screen mode. | |||
|
|
|||
| The presentations contain a number of query examples. | |||
| We recommend that you download `CodeQL for Visual Studio Code <https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up.html>`__ and add the example database for each presentation so that you can find the bugs mentioned in the slides. | |||
| We recommend that you download `CodeQL for Visual Studio Code <https://help.semmle.com/codeql/codeql-for-vscode/procedures/setting-up.html>`__ and add the example database for each presentation so that you can find the bugs mentioned in the slides. | |||
There was a problem hiding this comment.
Was this space added on purpose?
| @@ -11,7 +11,7 @@ CodeQL includes queries to find the most relevant and interesting problems for e | |||
| - **Alert queries**: queries that highlight issues in specific locations in your code. | |||
| - **Path queries**: queries that describe the flow of information between a source and a sink in your code. | |||
|
|
|||
| You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/about-queries#what-are-query-packs>`__ to analyze your projects in `LGTM <https://lgtm.com>`__, use them to analyze a database with the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__. | |||
| You can add custom queries to `custom query packs <https://lgtm.com/help/lgtm/about-queries#what-are-query-packs>`__ to analyze your projects in `LGTM <https://lgtm.com>`__, use them to analyze a database with the "`CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__" ," or you can contribute to the standard CodeQL queries in our `open source repository on GitHub <https://github.com/github/codeql>`__. | |||
There was a problem hiding this comment.
Is the double quote after the comma on purpose?
| - If you are adding a custom query to a query pack for analysis using LGTM , see `Writing custom queries to include in LGTM analysis <https://lgtm.com/help/lgtm/writing-custom-queries>`__. | ||
| - If you are analyzing a database using the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__, your query metadata must contain ``@kind``. | ||
| - If you are analyzing a database using the "`CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__" ," your query metadata must contain ``@kind``. |
There was a problem hiding this comment.
Is the double quote after the comma on purpose?
| @@ -123,12 +124,13 @@ Contributing queries | |||
| Contributions to the standard queries and libraries are very welcome. For more information, see our `contributing guidelines <https://github.com/github/codeql/blob/master/CONTRIBUTING.md>`__. | |||
| If you are contributing a query to the open source GitHub repository, writing a custom query for LGTM, or using a custom query in an analysis with the CodeQL CLI, then you need to include extra metadata in your query to ensure that the query results are interpreted and displayed correctly. See the following topics for more information on query metadata: | |||
|
|
|||
| - :doc:`Metadata for CodeQL queries <query-metadata>` | |||
| - ":doc:`Metadata for CodeQL queries <query-metadata>`" | |||
|
|
|||
There was a problem hiding this comment.
Is the empty line here on purpose?
| - If you are running a query in the query console on LGTM or with the CodeQL extension for VS Code, metadata is not mandatory. However, if you want your results to be displayed as either an 'alert' or a 'path', you must specify the correct ``@kind`` property, as explained below. For more information, see `Using the query console <https://lgtm.com/help/lgtm/using-query-console>`__ on LGTM.com and `Analyzing your projects <https://help.semmle.com/codeql/codeql-for-vscode/procedures/using-extension.html>`__ in the CodeQL for VS Code help. | ||
|
|
||
| .. pull-quote:: | ||
|
|
||
| Note | ||
|
|
||
| Queries that are contributed to the open source repository, added to a query pack in LGTM, or used to analyze a database with the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__ must have a query type (``@kind``) specified. The ``@kind`` property indicates how to interpret and display the results of the query analysis: | ||
| Queries that are contributed to the open source repository, added to a query pack in LGTM, or used to analyze a database with the `CodeQL CLI <https://help.semmle.com/codeql/codeql-cli.html>`__ must have a query type (``@kind``) specified. The ``@kind`` property indicates how to interpret and display the results of the query analysis: |
There was a problem hiding this comment.
Was this space added on purpose?
|
|
||
| Query metadata | ||
| ============== | ||
|
|
||
| Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see :doc:`Metadata for CodeQL queries <query-metadata>`. The exact metadata requirement depends on how you are going to run your query: | ||
| Query metadata is used to identify your custom queries when they are added to the GitHub repository or used in your analysis. Metadata provides information about the query's purpose, and also specifies how to interpret and display the query results. For a full list of metadata properties, see ":doc:`Metadata for CodeQL queries <query-metadata>`" |
There was a problem hiding this comment.
metadata>`"
This double quote seems to be redundant because the corresponding quote is already in line 44.
Though is this line wrapping (between line 43 & 44) here on purpose?
stray quote
edb2224 to
0dbe64e
Compare
hubwriter
previously approved these changes
Aug 12, 2020
docs/language/learn-ql/writing-queries/introduction-to-queries.rst
Outdated
Show resolved
Hide resolved
Hi @Marcono1234. Thanks taking the time to review this. I think I've now addressed the various issues you spotted. |
Co-authored-by: Alistair Christie <54933897+hubwriter@users.noreply.github.com>
|
Thanks for the suggestions @hubwriter. All addressed now. Please could you give this another approval? |
Marcono1234
reviewed
Aug 12, 2020
| @@ -148,10 +149,11 @@ The configuration class is accessed by importing the data flow library. This cla | |||
| - ``isSource()`` defines where data may flow from. | |||
| - ``isSink()`` defines where data may flow to. | |||
|
|
|||
| For further information on using the configuration class in your analysis see the sections on global data flow in :doc:`Analyzing data flow in C/C++ <../cpp/dataflow>` and :doc:`Analyzing data flow in C# <../csharp/dataflow>`. | |||
| For more information on using the configuration class in your analysis see the sections on global data flow in ":doc:`Analyzing data flow in C/C++ <../cpp/dataflow>`" | |||
| and ":doc:`Analyzing data flow in C# <../csharp/dataflow>`." | |||
There was a problem hiding this comment.
Is this line wrapped here on purpose?
shati-patel
approved these changes
Aug 14, 2020
|
@jf205 - I'm going to merge this PR since it looks complete. (I have an upcoming PR touching similar files and I want to avoid conflicts 🙈 ) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Follow up to https://github.com/github/semmle-code/pull/37473 (it fixes some more of https://github.com/github/semmle-docs/issues/218.)
This PR updates the links in the Learning CodeQL help to match the style used in the GitHub docs. I'll deal with the QL language reference in a separate PR.
Summary of changes
I've enclosed the following links in double quotes:
The following do not need to be in double quotes: