compilers: Update comments and docstrings

To be more accurate and better placed

mesonbuild/compilers/c.py

@@ -391,11 +391,12 @@ def get_options(self) -> 'MutableKeyedOptionDictType':
         std_opt.set_versions(stds)
         return opts
 
-    # Elbrus C compiler does not have lchmod, but there is only linker warning, not compiler error.
-    # So we should explicitly fail at this case.
     def has_function(self, funcname: str, prefix: str, env: 'Environment', *,
                      extra_args: T.Optional[T.List[str]] = None,
                      dependencies: T.Optional[T.List['Dependency']] = None) -> CompileCheckResult:
+        # Elbrus C compiler does not have lchmod, but there is only linker
+        # warning, not compiler error.  So we should explicitly fail at this
+        # case.
         if funcname == 'lchmod':
             return CompileCheckResult(False)
         else:

mesonbuild/compilers/compilers.py

@@ -544,11 +544,32 @@ def has_members(self, typename: str, membernames: T.List[str],
                     prefix: str, env: 'Environment', *,
                     extra_args: T.Union[None, T.List[str], T.Callable[[CompileCheckMode], T.List[str]]] = None,
                     dependencies: T.Optional[T.List['Dependency']] = None) -> CompileCheckResult:
+        """Test if a given type (struct, class, etc) has specific members.
+
+        :param typename: The type whose members will be checked
+        :param membernames: The members to checkf or
+        :param prefix: A preamble to add to the top of the generated test code
+        :param env: The Meson Environment
+        :param extra_args: Any extra arguments to pass to the check, defaults to None
+        :param dependencies: A list of Meson Dependency objects, defaults to None
+        :raises EnvironmentException: If the given compiler does not implement this check
+        :return: a :class:`CompileCheckResult`
+        """
         raise EnvironmentException('%s does not support has_member(s) ' % self.get_id())
 
     def has_type(self, typename: str, prefix: str, env: 'Environment',
                  extra_args: T.Union[T.List[str], T.Callable[[CompileCheckMode], T.List[str]]], *,
                  dependencies: T.Optional[T.List['Dependency']] = None) -> CompileCheckResult:
+        """Test if a given type exists.
+
+        :param typename: The type whose members will be checked
+        :param prefix: A preamble to add to the top of the generated test code
+        :param env: The Meson Environment
+        :param extra_args: Any extra arguments to pass to the check, defaults to None
+        :param dependencies: A list of Meson Dependency objects, defaults to None
+        :raises EnvironmentException: If the given compiler does not implement this check
+        :return: a :class:`CompileCheckResult`
+        """
         raise EnvironmentException('%s does not support has_type ' % self.get_id())
 
     def symbols_have_underscore_prefix(self, env: 'Environment') -> bool:
@@ -645,8 +666,14 @@ def has_header(self, hname: str, prefix: str, env: 'Environment', *,
         # error "You thought you could use this, LOLZ!"
         ```
 
-        Use check_header if your header only works in some cases.
+        Use :method:`check_header` if your header only works in some cases.
 
+        :param hname: the name of the header to check for
+        :param prefix: A preamble to add to the top of the generated test code
+        :param env: The Meson Environment
+        :param extra_args: Any extra arguments to pass to the check, defaults to None
+        :param dependencies: A list of Meson Dependency objects, defaults to None
+        :raises EnvironmentException: If the given compiler does not implement this check
         :return: a :class:`CompileCheckResult`
         """
         raise EnvironmentException('Language %s does not support header checks.' % self.get_display_language())
@@ -655,6 +682,17 @@ def has_header_symbol(self, hname: str, symbol: str, prefix: str,
                           env: 'Environment', *,
                           extra_args: T.Union[None, T.List[str], T.Callable[[CompileCheckMode], T.List[str]]] = None,
                           dependencies: T.Optional[T.List['Dependency']] = None) -> CompileCheckResult:
+        """Test if a given header has a specific symbol defined.
+
+        :param hname: the name of the header to check in
+        :param symbol: The symbol to look for
+        :param prefix: A preamble to add to the top of the generated test code
+        :param env: The Meson Environment
+        :param extra_args: Any extra arguments to pass to the check, defaults to None
+        :param dependencies: A list of Meson Dependency objects, defaults to None
+        :raises EnvironmentException: If the given compiler does not implement this check
+        :return: a :class:`CompileCheckResult`
+        """
         raise EnvironmentException('Language %s does not support header symbol checks.' % self.get_display_language())
 
     def run(self, code: 'mesonlib.FileOrString', env: 'Environment',
@@ -726,6 +764,12 @@ def has_function(self, funcname: str, prefix: str, env: 'Environment', *,
                      dependencies: T.Optional[T.List['Dependency']] = None) -> CompileCheckResult:
         """See if a function exists.
 
+        :param funcname: the name of the function to check for
+        :param prefix: A preamble to add to the top of the generated test code
+        :param env: The Meson Environment
+        :param extra_args: Any extra arguments to pass to the check, defaults to None
+        :param dependencies: A list of Meson Dependency objects, defaults to None
+        :raises EnvironmentException: If the given compiler does not implement this check
         :return: a :class:`CompileCheckResult`
         """
         raise EnvironmentException('Language %s does not support function checks.' % self.get_display_language())
@@ -759,6 +803,9 @@ def get_program_dirs(self, env: 'Environment') -> T.List[str]:
     def has_multi_arguments(self, args: T.List[str], env: 'Environment') -> CompileCheckResult:
         """Checks if the compiler has all of the arguments.
 
+        :param args: The arguments to test
+        :param env: The Meson Environment
+        :raises EnvironmentException: If the given compiler does not implement this check
         :return: a :class:`CompileCheckResult`
         """
         raise EnvironmentException(
@@ -768,6 +815,9 @@ def has_multi_arguments(self, args: T.List[str], env: 'Environment') -> CompileC
     def has_multi_link_arguments(self, args: T.List[str], env: 'Environment') -> CompileCheckResult:
         """Checks if the linker has all of the arguments.
 
+        :param args: The arguments to test
+        :param env: The Meson Environment
+        :raises EnvironmentException: If the given compiler does not implement this check
         :return: a :class:`CompileCheckResult`
         """
         return self.linker.has_multi_arguments(args, env)
@@ -961,6 +1011,15 @@ def get_win_subsystem_args(self, value: str) -> T.List[str]:
         return self.linker.get_win_subsystem_args(value)
 
     def has_func_attribute(self, name: str, env: 'Environment') -> CompileCheckResult:
+        """Test if the compiler supports various attribute modifiers
+
+        These are usually in the form `__attribute__(...)` or `__declspec(...)`
+
+        :param name: The name of the attribute to test for
+        :param env: The Meson Environment
+        :raises EnvironmentException: If the given compiler doesn't implement this check
+        :return: A :class:`CompileCheckResult`
+        """
         raise EnvironmentException(
             f'Language {self.get_display_language()} does not support function attributes.')
 
@@ -1310,6 +1369,12 @@ def compiles(self, code: 'mesonlib.FileOrString', env: 'Environment', *,
                  disable_cache: bool = False) -> CompileCheckResult:
         """Run a compilation or link test to see if code can be compiled/linked.
 
+        :param code: A string or File of test code
+        :param env: The Meson Environment
+        :param extra_args: Extra arguments to pass to the compiler, defaults to None
+        :param dependencies: A list of extra Dependencies, defaults to None
+        :param mode: How to test, either Compile, Link, or Preprocess; defaults to CompileCheckMode.COMPILE
+        :param disable_cache: If true run the check even if we've already run it before, defaults to False
         :return: A :class:`CompileCheckResult`
         """
         with self._build_wrapper(code, env, extra_args, dependencies, mode, disable_cache=disable_cache) as p:
@@ -1320,6 +1385,15 @@ def links(self, code: 'mesonlib.FileOrString', env: 'Environment', *,
               extra_args: T.Union[None, T.List[str], CompilerArgs, T.Callable[[CompileCheckMode], T.List[str]]] = None,
               dependencies: T.Optional[T.List['Dependency']] = None,
               disable_cache: bool = False) -> CompileCheckResult:
+        """Run a compilation or link test to see if code can be compiled/linked.
+
+        :param code: A string or File of test code
+        :param env: The Meson Environment
+        :param extra_args: Extra arguments to pass to the compiler, defaults to None
+        :param dependencies: A list of extra Dependencies, defaults to None
+        :param disable_cache: If true run the check even if we've already run it before, defaults to False
+        :return: A :class:`CompileCheckResult`
+        """
         if compiler:
             with compiler._build_wrapper(code, env, dependencies=dependencies, want_output=True) as r:
                 objfile = mesonlib.File.from_absolute_file(r.output_name)

mesonbuild/compilers/cpp.py

@@ -606,11 +606,12 @@ def get_options(self) -> 'MutableKeyedOptionDictType':
         std_opt.set_versions(cpp_stds, gnu=True)
         return opts
 
-    # Elbrus C++ compiler does not have lchmod, but there is only linker warning, not compiler error.
-    # So we should explicitly fail at this case.
     def has_function(self, funcname: str, prefix: str, env: 'Environment', *,
                      extra_args: T.Optional[T.List[str]] = None,
                      dependencies: T.Optional[T.List['Dependency']] = None) -> CompileCheckResult:
+        # Elbrus C++ compiler does not have lchmod, but there is only linker
+        # warning, not compiler error.  So we should explicitly fail at this
+        # case.
         if funcname == 'lchmod':
             return CompileCheckResult(False)
         else: