Bug 559674: Improve doc and javadoc
eliminate use of 'Language ID'
eliminate use of 'Language Setting'
eliminate use of 'Language Setting Provider' and 'lsp'
Change-Id: I7358ec99fde008d2b1a8c99fa294acac3469b20e
Signed-off-by: Martin Weber <fifteenknots505@gmail.com>
diff --git a/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/builtins-detection.xhtml b/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/builtins-detection.xhtml
index da10023..ff1d835 100644
--- a/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/builtins-detection.xhtml
+++ b/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/builtins-detection.xhtml
@@ -20,7 +20,7 @@
<p>CDT CMake support can detect compiler-built-in include paths and preprocessor macros.<br/>
Unfortunately, it has no knowledge about the generated build system structure, the <code>compile_commads.json</code>
file generated by CMake only reports source-files. To avoid the cost of running the built-ins detector for
- <strong>each</strong> source-file, CDT CMAke support assumes that compiler built-ins
+ <strong>each</strong> source-file, CDT CMake support assumes that compiler built-ins
are the same for each source-file in a CMake project. Therefore, detection is run just once
(on the first source file found per language) per Eclipse project.
</p>
@@ -106,16 +106,6 @@
</tr>
</tbody>
</table>
- <p>
- Please note that for performance reasons, compiler built-ins assumes that compiler built-ins
- are the <strong>same for each source-file</strong> in a CMake project and built-ins detection is run only for the
- first source-file.<br/>
- In contrast, CMake has commands like <code>add_compile_options</code>, <code>target_compile_features</code> and
- <code>target_compile_options</code> allowing you to specify the language standard and
- non-standard system include paths on a
- <strong>per-source-directory</strong> or <strong>per-artifact</strong> level.
- Hence the syntax highlighting may not always exactly reflect the built-ins specified on that levels.
- </p>
<p>Remarks:</p>
<ul style="list-style-type:none">
<li id="fw-help-gcc">[1] Help wanted! To implement this, the output of <code>gcc -E -P -dM -Wp,-v emty.c</code>
@@ -126,6 +116,6 @@
<h3>Compilers supported through separate plug-ins</h3>
<!-- extra compilers go here -->
- <anchor id="extra_lsp_detection_participant_builtins_enhanced_list"/>
+ <anchor id="extra_detection_participant_builtins_enhanced_list"/>
</body>
</html>
\ No newline at end of file
diff --git a/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/languageSettingsProviders.xhtml b/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/languageSettingsProviders.xhtml
index 85b5394..edf7d56 100644
--- a/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/languageSettingsProviders.xhtml
+++ b/cmake/org.eclipse.cdt.cmake.is.core.doc/doc/html/languageSettingsProviders.xhtml
@@ -2,10 +2,7 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
-<title>Available Language Setting Providers</title>
-<!--
-TODO update this! We do not use Language Setting Providers in core build!
--->
+<title>Available Compiler Support for the Indexer</title>
<style type="text/css">
table, th, td {
border: 1px solid black;
@@ -17,23 +14,10 @@
</head>
<body>
<h1>Preprocessor Include Paths, Macros</h1>
- <P>Include paths and preprocessor macros for the CDT source code indexer are supplied by
- <strong>Language Settings Providers</strong> using the
- <a href="PLUGINS_ROOT/org.eclipse.cdt.doc.user/tasks/cdt_t_sd.htm">Scanner Discovery</a>
- mechanism. The C/C++/CUDA editors use the indexer to improve syntax highlighting, allowing you to jump to
+ <P>The C/C++/CUDA editors use the CDT indexer to improve syntax highlighting, allowing you to jump to
macro definitions and to browse through include files.
</P>
- <p>The CDT CMake support provides two <a href="PLUGINS_ROOT/org.eclipse.cdt.doc.user/concepts/cdt_c_scanner_discovery.htm">Language Settings Providers</a>:</p>
-
- <h2>CMAKE_EXPORT_COMPILE_COMMANDS Parser</h2>
- <p>This provider instructs CMake to generate a file that contains all the compiler command-lines
- which will be executed when a project is build.<br/>
- The provider will parse that file and feed any preprocessor include path, macro definition or
- macro undefine that originates from your <em>CMakeLists.txt</em> files to the indexer.<br/>
- Parsing is done rarely, since the internal cache is invalidated only when the
- file`s time-stamp is newer, so it should be reasonably fast.
- </p>
- <p>The following table lists the compiler executables supported by the CMAKE_EXPORT_COMPILE_COMMANDS Parser.</p>
+ <p>The following table lists the compiler executables supported by the CDT CMake build integration.</p>
<table id="overview_table" style="border-collapse:collapse">
<thead>
<tr>
@@ -117,9 +101,8 @@
<!-- extra compilers go here -->
<anchor id="extra_detection_participant_list"/>
- <h2>CMAKE_EXPORT_COMPILE_COMMANDS Compiler Built-ins</h2>
- <p>This provider works similar to <q>CMAKE_EXPORT_COMPILE_COMMANDS Parser</q>, but invokes
- the compiler with arguments to get the include paths and preprocessor macros
+ <h2>CDT CMake build integration Compiler Built-ins detection</h2>
+ <p>This feature also invokes tries to get the include paths and preprocessor macros
<strong>built-in to the compiler</strong>.<br/>
Note that this works only for compilers that supporting it.
See <a href="builtins-detection.xhtml">built-ins detection</a> for supported compilers.
diff --git a/cmake/org.eclipse.cdt.cmake.is.core/schema/participant.exsd b/cmake/org.eclipse.cdt.cmake.is.core/schema/participant.exsd
index f8755b0..1771ee6 100644
--- a/cmake/org.eclipse.cdt.cmake.is.core/schema/participant.exsd
+++ b/cmake/org.eclipse.cdt.cmake.is.core/schema/participant.exsd
@@ -111,11 +111,11 @@
<p>
To provide online help that lists the supported compilers anlong with and the recognized arguments,
the extension point <code>org.eclipse.help.contentExtension</code> can be used.<br/>
-Plugin <i>de.marw.cdt.cmake.core</i> provides predefined help-anchors that allow to integrate the online help:
+Plugin <i>org.eclipse.cdt.cmake.is.core.doc</i> provides predefined help-anchors that allow to integrate the online help:
<ol>
<li><i>extra_detection_participant_list</i> for the commandline parser,</li>
<li><i>extra_detection_participant_builtins_list</i> and
-<i>extra_lsp_detection_participant_builtins_enhanced_list</i> for the compiler built-ins parser.</li>
+<i>extra_detection_participant_builtins_enhanced_list</i> for the compiler built-ins parser.</li>
</ol>
Example file <code>help_content_extension.xml</code>:
<pre>
diff --git a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/internal/package-info.java b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/internal/package-info.java
deleted file mode 100644
index 2b21a12..0000000
--- a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/internal/package-info.java
+++ /dev/null
@@ -1,15 +0,0 @@
-/*******************************************************************************
- * Copyright (c) 2019 Martin Weber.
- *
- * Content is provided to you under the terms and conditions of the Eclipse Public License Version 2.0 "EPL".
- * A copy of the EPL is available at http://www.eclipse.org/legal/epl-2.0.
- *
- * SPDX-License-Identifier: EPL-2.0
- *******************************************************************************/
-
-/**
- * Language Setting Providers
- *
- * @author Martin Weber
- */
-package org.eclipse.cdt.cmake.is.core.internal;
\ No newline at end of file
diff --git a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/package-info.java b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/package-info.java
index 9cd8170..305c5ab 100644
--- a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/package-info.java
+++ b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/package-info.java
@@ -8,7 +8,10 @@
*******************************************************************************/
/**
- * Language Setting Providers
+ * Classes and interfaces to parse a file 'compile_commands.json' produced by
+ * cmake and to generate information about preprocessor symbols and include
+ * paths of the files being compiled in order to support the CDT indexer/ syntax
+ * highlighting.
*
* @author Martin Weber
*/
diff --git a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/DefaultToolCommandlineParser.java b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/DefaultToolCommandlineParser.java
index d39cbb2..2edfbe7 100644
--- a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/DefaultToolCommandlineParser.java
+++ b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/DefaultToolCommandlineParser.java
@@ -35,13 +35,6 @@
/**
* Constructs a new object with the given values.
- * <p>
- * NOTE: Concerning the {@code languageID} argument, please note that CDT
- * expects "org.eclipse.cdt.core.gcc" for the C language and
- * "org.eclipse.cdt.core.g++" for the C++ language. Some extension to CDT may
- * recognize different language IDs, such as
- * "com.nvidia.cuda.toolchain.language.cuda.cu"
- * </p>
*
* @param responseFileArglet the parsers for the response-file
* command-line argument for the tool or
@@ -114,10 +107,10 @@
private final IPath cwd;
/**
- * @param cwd the current working directory of the compiler at the time of its
- * invocation
- *
- * @throws NullPointerException if any of the arguments is {@code null}
+ * @param cwd the current working directory of the compiler at the time of its
+ * invocation
+ *
+ * @throws NullPointerException if any of the arguments is {@code null}
*/
public ParserHandler(IPath cwd) {
this.cwd = Objects.requireNonNull(cwd, "cwd"); //$NON-NLS-1$
diff --git a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/IToolDetectionParticipant.java b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/IToolDetectionParticipant.java
index 038694a..1a3578f 100644
--- a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/IToolDetectionParticipant.java
+++ b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/IToolDetectionParticipant.java
@@ -12,15 +12,22 @@
import java.util.Optional;
/**
- * Responsible to match the first argument (the tool command) of a command-line
- * and to provide a parser for the tool-specific command-line arguments.
+ * Participates in generating {@link org.eclipse.cdt.core.parser.IScannerInfo}
+ * objects for the files being compiled in order to support the CDT indexer/
+ * syntax highlighting.<br>
+ * Generation of the {@code IScannerInfo} objects is done by analyzing a
+ * {@code compile_commands.json} file produced by cmake.
+ * <p>
+ * This interface is the expected interface for extensions provided for the
+ * {@code org.eclipse.cdt.cmake.is.core.detectionParticipant} extension point.
+ * </p>
*
* @author Martin Weber
*/
public interface IToolDetectionParticipant {
/**
- * Gets the for the parser for the tool-specific command-line arguments.
+ * Gets the parser for the tool-specific command-line arguments.
*
* @return the parser, never {@code null}
*/
@@ -37,14 +44,14 @@
/**
* Gets, whether the parser for the tool arguments can properly parse the
- * specified command-line string. If so, the remaining arguments of the
- * command-line are returned.
+ * specified command-line string.
*
* @param commandLine the command line to match
* @param matchBackslash whether to match on file system paths with backslashes
* in the compiler argument or to match an paths with
* forward slashes
- * @return An empty {@code Optional} if the matcher did not match the tool name in the
+ * @return An empty {@code Optional} if the tool/compiler handled by this object
+ * does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@@ -52,9 +59,8 @@
/**
* Gets, whether the parser for the tool arguments can properly parse the
- * specified command-line string. If so, the remaining arguments of the
- * command-line are returned. This is time-consuming, since it creates a Matcher
- * object on each invocation.
+ * specified command-line string. This may be time-consuming, since it creates a
+ * Matcher object on each invocation.
*
* @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes
@@ -62,7 +68,8 @@
* forward slashes
* @param versionRegex a regular expression that matches the version string in
* the name of the tool to detect.
- * @return An empty {@code Optional} if the matcher did not match the tool name in the
+ * @return An empty {@code Optional} if the tool/compiler handled by this object
+ * does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@@ -70,14 +77,14 @@
/**
* Gets, whether the parser for the tool arguments can properly parse the
- * specified command-line string. If so, the remaining arguments of the
- * command-line are returned.
+ * specified command-line string.
*
* @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes
* in the compiler argument or to match an paths with
* forward slashes
- * @return An empty {@code Optional} if the matcher did not match the tool name in the
+ * @return An empty {@code Optional} if the tool/compiler handled by this object
+ * does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@@ -85,9 +92,8 @@
/**
* Gets, whether the parser for the tool arguments can properly parse the
- * specified command-line string. If so, the remaining arguments of the
- * command-line are returned. This is time-consuming, since it creates a Matcher
- * object on each invocation.
+ * specified command-line string. This may be time-consuming, since it creates a
+ * Matcher object on each invocation.
*
* @param commandLine the command-line to match
* @param matchBackslash whether to match on file system paths with backslashes
@@ -95,7 +101,8 @@
* forward slashes
* @param versionRegex a regular expression that matches the version string in
* the name of the tool to detect.
- * @return An empty {@code Optional} if the matcher did not match the tool name in the
+ * @return An empty {@code Optional} if the tool/compiler handled by this object
+ * does not match the first argument (the tool name) from the
* command-line string. Otherwise, if the tool name matches, a
* MatchResult holding the de-composed command-line is returned.
*/
@@ -111,7 +118,7 @@
/**
* @param command the command from the command-line, without the argument
- * string. . If the command contains space characters, the
+ * string. If the command contains space characters, the
* surrounding quotes must have been removed,
* @param arguments the remaining arguments from the command-line, without the
* command
diff --git a/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/package-info.java b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/package-info.java
new file mode 100644
index 0000000..5ad4901
--- /dev/null
+++ b/cmake/org.eclipse.cdt.cmake.is.core/src/main/java/org/eclipse/cdt/cmake/is/core/participant/package-info.java
@@ -0,0 +1,18 @@
+/*******************************************************************************
+ * Copyright (c) 2019 Martin Weber.
+ *
+ * Content is provided to you under the terms and conditions of the Eclipse Public License Version 2.0 "EPL".
+ * A copy of the EPL is available at http://www.eclipse.org/legal/epl-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *******************************************************************************/
+
+/**
+ * Classes and interfaces allowing for third-party compiler vendors so they can
+ * provide a plugin that understands their compiler specific command-line
+ * options and participates in command-line analysis in order to support the CDT
+ * indexer/ syntax highlighting.
+ *
+ * @author Martin Weber
+ */
+package org.eclipse.cdt.cmake.is.core.participant;
\ No newline at end of file
diff --git a/cmake/org.eclipse.cdt.cmake.is.nvidia/help_content_extension.xml b/cmake/org.eclipse.cdt.cmake.is.nvidia/help_content_extension.xml
index d7af548..7e49b10 100644
--- a/cmake/org.eclipse.cdt.cmake.is.nvidia/help_content_extension.xml
+++ b/cmake/org.eclipse.cdt.cmake.is.nvidia/help_content_extension.xml
@@ -5,5 +5,5 @@
<contribution content="doc/compiler.xhtml#builtins"
path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_detection_participant_builtins_list"/>
<contribution content="doc/compiler.xhtml#builtins_enhanced"
- path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_lsp_detection_participant_builtins_enhanced_list"/>
+ path="/de.marw.cdt.cmake.core/doc/html/builtins-detection.xhtml#extra_detection_participant_builtins_enhanced_list"/>
</contentExtension>
\ No newline at end of file
