Improve documentation by clarifying the purpose of different tools (#357

) * Fix spelling of PC-lint tool * Clarify that PEP257 is for docstring conventions * Clarify that mypy does static type analysis * Clarify that pydocstyle is for PEP8 code conventions Signed-off-by: Bi0T1N <[email protected]> Co-authored-by: Bi0T1N <[email protected]>
ament · Mar 22, 2022 · 5aa4153 · 5aa4153
1 parent 467a5d5
commit 5aa4153
Show file tree

Hide file tree

Showing 17 changed files with 23 additions and 21 deletions.
diff --git a/ament_cmake_mypy/doc/index.rst b/ament_cmake_mypy/doc/index.rst
@@ -1,7 +1,7 @@
 ament_cmake_mypy
 ==================
 
-Checks the code syntax and style of Python source files using `mypy
+Performs a static type analysis of Python source files using `mypy
 <http://mypy.readthedocs.io/>`_.
 Files with the following extensions are being considered: ``.py``.
 

diff --git a/ament_cmake_pclint/cmake/ament_pclint.cmake b/ament_cmake_pclint/cmake/ament_pclint.cmake
@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Add a test to perform static code analysis with pclint.
+# Add a test to perform static code analysis with PC-lint.
 #
 # :param TESTNAME: the name of the test, default: "pclint"
 # :type TESTNAME: string

diff --git a/ament_cmake_pclint/doc/index.rst b/ament_cmake_pclint/doc/index.rst
@@ -1,7 +1,7 @@
 ament_pclint
 ==============
 
-Performs a static code analysis of C / C++ source files using `PCLint
+Performs a static code analysis of C / C++ source files using `PC-lint
 <http://www.gimpel.com/html/index.htm>`_.
 
 How to run the check from the command line?

diff --git a/ament_cmake_pclint/package.xml b/ament_cmake_pclint/package.xml
@@ -5,7 +5,7 @@
   <version>0.12.1</version>
   <description>
     The CMake API for ament_pclint to perform static code analysis on C/C++
-    code using PCLint.
+    code using PC-lint.
   </description>
 
   <maintainer email="[email protected]">Michael Jeronimo</maintainer>

diff --git a/ament_cmake_pep257/cmake/ament_cmake_pep257_lint_hook.cmake b/ament_cmake_pep257/cmake/ament_cmake_pep257_lint_hook.cmake
@@ -14,6 +14,6 @@
 
 file(GLOB_RECURSE _python_files FOLLOW_SYMLINKS "*.py")
 if(_python_files)
-  message(STATUS "Added test 'pep257' to check Python code against some of the style conventions in PEP 257")
+  message(STATUS "Added test 'pep257' to check Python code against some of the docstring style conventions in PEP 257")
   ament_pep257()
 endif()
diff --git a/ament_cmake_pep257/doc/index.rst b/ament_cmake_pep257/doc/index.rst
@@ -1,8 +1,8 @@
 ament_pep257
 ============
 
-Checks the code style of Python source files using `pep257
-<http://pep257.readthedocs.org/>`_.
+Performs a static analysis to check compliance with Python docstring conventions
+of Python source files using `pep257 <http://pep257.readthedocs.org/>`_.
 Files with the following extensions are being considered: ``.py``.
 
 

diff --git a/ament_cmake_pep257/package.xml b/ament_cmake_pep257/package.xml
@@ -4,7 +4,7 @@
   <name>ament_cmake_pep257</name>
   <version>0.12.1</version>
   <description>
-    The CMake API for ament_pep257 to check code against the style conventions in
+    The CMake API for ament_pep257 to check code against the docstring style conventions in
     PEP 257.
   </description>
 

diff --git a/ament_cmake_pycodestyle/doc/index.rst b/ament_cmake_pycodestyle/doc/index.rst
@@ -1,7 +1,8 @@
 ament_cmake_pycodestyle
 =======================
 
-Checks the code style of Python source files using `pycodestyle
+Checks the code of Python source files against some of the style
+conventions in PEP 8 using `pycodestyle
 <http://pycodestyle.readthedocs.org/>`_.
 Files with the following extensions are being considered: ``.py``.
 

diff --git a/ament_mypy/ament_mypy/main.py b/ament_mypy/ament_mypy/main.py
@@ -28,7 +28,7 @@
 
 
 def main(argv: List[str] = sys.argv[1:]) -> int:
-    """Command line tool for linting files with mypy."""
+    """Command line tool for static type analysis with mypy."""
     parser = argparse.ArgumentParser(
         description='Check code using mypy',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter

diff --git a/ament_mypy/doc/index.rst b/ament_mypy/doc/index.rst
@@ -1,7 +1,7 @@
 ament_mypy
 ============
 
-Checks the code syntax and style of Python source files using `mypy
+Performs a static type analysis of Python source files using `mypy
 <https://mypy.readthedocs.io/>`_.
 Files with the following extensions are being considered: ``.py``.
 

diff --git a/ament_pclint/ament_pclint/main.py b/ament_pclint/ament_pclint/main.py
@@ -32,7 +32,7 @@ def main(argv=sys.argv[1:]):
     extensions = ['c', 'cc', 'cpp', 'cxx', 'c++']
 
     parser = argparse.ArgumentParser(
-        description='Perform static code analysis using pclint.',
+        description='Perform static code analysis using PC-lint.',
         formatter_class=argparse.ArgumentDefaultsHelpFormatter)
     parser.add_argument(
         'paths',

diff --git a/ament_pclint/doc/index.rst b/ament_pclint/doc/index.rst
@@ -1,7 +1,7 @@
 ament_pclint
 ==============
 
-Performs a static code analysis of C / C++ source files using `PCLint
+Performs a static code analysis of C / C++ source files using `PC-lint
 <http://www.gimpel.com/html/index.htm>`_.
 
 

diff --git a/ament_pclint/package.xml b/ament_pclint/package.xml
@@ -4,7 +4,7 @@
   <name>ament_pclint</name>
   <version>0.12.1</version>
   <description>
-    The ability to perform static code analysis on C/C++ code using pclint
+    The ability to perform static code analysis on C/C++ code using PC-lint
     and generate xUnit test result files.
   </description>
 

diff --git a/ament_pclint/setup.py b/ament_pclint/setup.py
@@ -48,9 +48,9 @@
         'Programming Language :: Python',
         'Topic :: Software Development',
     ],
-    description='Static code analysis on C/C++ code using PCLint.',
+    description='Static code analysis on C/C++ code using PC-lint.',
     long_description="""\
-The ability to perform static code analysis on C/C++ code using PCLint
+The ability to perform static code analysis on C/C++ code using PC-lint
 and generate xUnit test result files.""",
     license='Apache License, Version 2.0',
     tests_require=['pytest'],

diff --git a/ament_pep257/doc/index.rst b/ament_pep257/doc/index.rst
@@ -1,8 +1,8 @@
 ament_pep257
 ============
 
-Checks the docstring style of Python source files using `pep257
-<http://pep257.readthedocs.org/>`_.
+Performs a static analysis to check compliance with Python docstring conventions
+of Python source files using `pep257 <http://pep257.readthedocs.org/>`_.
 Files with the following extensions are being considered: ``.py``.
 
 

diff --git a/ament_pep257/package.xml b/ament_pep257/package.xml
@@ -4,8 +4,8 @@
   <name>ament_pep257</name>
   <version>0.12.1</version>
   <description>
-    The ability to check code against the style conventions in PEP 8 and
-    generate xUnit test result files.
+    The ability to check code against the docstring style conventions in
+    PEP 257 and generate xUnit test result files.
   </description>
 
   <maintainer email="[email protected]">Michael Jeronimo</maintainer>

diff --git a/ament_pycodestyle/doc/index.rst b/ament_pycodestyle/doc/index.rst
@@ -1,7 +1,8 @@
 ament_pycodestyle
 =================
 
-Checks the code style of Python source files using `pycodestyle
+Checks the code of Python source files against some of the style
+conventions in PEP 8 using `pycodestyle
 <http://pycodestyle.readthedocs.org/>`_.
 Files with the following extensions are being considered: ``.py``.