pylint/extensions/docparams.py
def check_arguments_in_docstring(
        self, doc, arguments_node, warning_node, accept_no_param_doc=None
    ):
        """Check that all parameters in a function, method or class constructor
        on the one hand and the parameters mentioned in the parameter
        documentation (e.g. the Sphinx tags 'param' and 'type') on the other
        hand are consistent with each other.

        * Undocumented parameters except 'self' are noticed.
        * Undocumented parameter types except for 'self' and the ``*<args>``
          and ``**<kwargs>`` parameters are noticed.
        * Parameters mentioned in the parameter documentation that don't or no
          longer exist in the function parameter list are noticed.
        * If the text "For the parameters, see" or "For the other parameters,
          see" (ignoring additional whitespace) is mentioned in the docstring,
          missing parameter documentation is tolerated.
        * If there's no Sphinx style, Google style or NumPy style parameter
          documentation at all, i.e. ``:param`` is never mentioned etc., the
          checker assumes that the parameters are documented in another format
          and the absence is tolerated.

        :param doc: Docstring for the function, method or class.
        :type doc: str

        :param arguments_node: Arguments node for the function, method or
            class constructor.
        :type arguments_node: :class:`astroid.scoped_nodes.Arguments`

        :param warning_node: The node to assign the warnings to
        :type warning_node: :class:`astroid.scoped_nodes.Node`

        :param accept_no_param_doc: Whether or not to allow no parameters
            to be documented.
            If None then this value is read from the configuration.
        :type accept_no_param_doc: bool or None
        """
        # Tolerate missing param or type declarations if there is a link to
        # another method carrying the same name.
        if not doc.doc:
            return

        if accept_no_param_doc is None:
            accept_no_param_doc = self.config.accept_no_param_doc
        tolerate_missing_params = doc.params_documented_elsewhere()

        # Collect the function arguments.
        expected_argument_names = {arg.name for arg in arguments_node.args}
        expected_argument_names.update(arg.name for arg in arguments_node.kwonlyargs)
        not_needed_type_in_docstring = self.not_needed_param_in_docstring.copy()

        if arguments_node.vararg is not None:
            expected_argument_names.add(arguments_node.vararg)
            not_needed_type_in_docstring.add(arguments_node.vararg)
        if arguments_node.kwarg is not None:
            expected_argument_names.add(arguments_node.kwarg)
            not_needed_type_in_docstring.add(arguments_node.kwarg)
        params_with_doc, params_with_type = doc.match_param_docs()

        # Tolerate no parameter documentation at all.
        if not params_with_doc and not params_with_type and accept_no_param_doc:
            tolerate_missing_params = True

        def _compare_missing_args(found_argument_names, message_id, not_needed_names):
            """Compare the found argument names with the expected ones and
            generate a message if there are arguments missing.

            :param set found_argument_names: argument names found in the
                docstring

            :param str message_id: pylint message id

            :param not_needed_names: names that may be omitted
            :type not_needed_names: set of str
            """
            if not tolerate_missing_params:
                missing_argument_names = (
                    expected_argument_names - found_argument_names
                ) - not_needed_names
                if missing_argument_names:
                    self.add_message(
                        message_id,
                        args=(", ".join(sorted(missing_argument_names)),),
                        node=warning_node,
                    )

        def _compare_different_args(found_argument_names, message_id, not_needed_names):
            """Compare the found argument names with the expected ones and
            generate a message if there are extra arguments found.

            :param set found_argument_names: argument names found in the
                docstring

            :param str message_id: pylint message id

            :param not_needed_names: names that may be omitted
            :type not_needed_names: set of str
            """
            differing_argument_names = (
                (expected_argument_names ^ found_argument_names)
                - not_needed_names
                - expected_argument_names
            )

            if differing_argument_names:
                self.add_message(
                    message_id,
                    args=(", ".join(sorted(differing_argument_names)),),
                    node=warning_node,
                )

        _compare_missing_args(
            params_with_doc, "missing-param-doc", self.not_needed_param_in_docstring
        )

        for index, arg_name in enumerate(arguments_node.args):
            if arguments_node.annotations[index]:
                params_with_type.add(arg_name.name)

        _compare_missing_args(
            params_with_type, "missing-type-doc", not_needed_type_in_docstring
        )

        _compare_different_args(
            params_with_doc, "differing-param-doc", self.not_needed_param_in_docstring
        )
        _compare_different_args(
            params_with_type, "differing-type-doc", not_needed_type_in_docstring
        )
def check_arguments_in_docstring(
        self, doc, arguments_node, warning_node, accept_no_param_doc=None
    ):
        """Check that all parameters in a function, method or class constructor
        on the one hand and the parameters mentioned in the parameter
        documentation (e.g. the Sphinx tags 'param' and 'type') on the other
        hand are consistent with each other.

        * Undocumented parameters except 'self' are noticed.
        * Undocumented parameter types except for 'self' and the ``*<args>``
          and ``**<kwargs>`` parameters are noticed.
        * Parameters mentioned in the parameter documentation that don't or no
          longer exist in the function parameter list are noticed.
        * If the text "For the parameters, see" or "For the other parameters,
          see" (ignoring additional whitespace) is mentioned in the docstring,
          missing parameter documentation is tolerated.
        * If there's no Sphinx style, Google style or NumPy style parameter
          documentation at all, i.e. ``:param`` is never mentioned etc., the
          checker assumes that the parameters are documented in another format
          and the absence is tolerated.

        :param doc: Docstring for the function, method or class.
        :type doc: str

        :param arguments_node: Arguments node for the function, method or
            class constructor.
        :type arguments_node: :class:`astroid.scoped_nodes.Arguments`

        :param warning_node: The node to assign the warnings to
        :type warning_node: :class:`astroid.scoped_nodes.Node`

        :param accept_no_param_doc: Whether or not to allow no parameters
            to be documented.
            If None then this value is read from the configuration.
        :type accept_no_param_doc: bool or None
        """
        # Tolerate missing param or type declarations if there is a link to
        # another method carrying the same name.
        if not doc.doc:
            return

        if accept_no_param_doc is None:
            accept_no_param_doc = self.config.accept_no_param_doc
        tolerate_missing_params = doc.params_documented_elsewhere()

        # Collect the function arguments.
        expected_argument_names = {arg.name for arg in arguments_node.args}
        expected_argument_names.update(arg.name for arg in arguments_node.kwonlyargs)
        not_needed_type_in_docstring = self.not_needed_param_in_docstring.copy()

        if arguments_node.vararg is not None:
            expected_argument_names.add(arguments_node.vararg)
            not_needed_type_in_docstring.add(arguments_node.vararg)
        if arguments_node.kwarg is not None:
            expected_argument_names.add(arguments_node.kwarg)
            not_needed_type_in_docstring.add(arguments_node.kwarg)
        params_with_doc, params_with_type = doc.match_param_docs()

        # Tolerate no parameter documentation at all.
        if not params_with_doc and not params_with_type and accept_no_param_doc:
            tolerate_missing_params = True

        def _compare_missing_args(found_argument_names, message_id, not_needed_names):
            """Compare the found argument names with the expected ones and
            generate a message if there are arguments missing.

            :param set found_argument_names: argument names found in the
                docstring

            :param str message_id: pylint message id

            :param not_needed_names: names that may be omitted
            :type not_needed_names: set of str
            """
            if not tolerate_missing_params:
                missing_argument_names = (
                    expected_argument_names - found_argument_names
                ) - not_needed_names
                if missing_argument_names:
                    self.add_message(
                        message_id,
                        args=(", ".join(sorted(missing_argument_names)),),
                        node=warning_node,
                    )

        def _compare_different_args(found_argument_names, message_id, not_needed_names):
            """Compare the found argument names with the expected ones and
            generate a message if there are extra arguments found.

            :param set found_argument_names: argument names found in the
                docstring

            :param str message_id: pylint message id

            :param not_needed_names: names that may be omitted
            :type not_needed_names: set of str
            """
            differing_argument_names = (
                (expected_argument_names ^ found_argument_names)
                - not_needed_names
                - expected_argument_names
            )

            if differing_argument_names:
                self.add_message(
                    message_id,
                    args=(", ".join(sorted(differing_argument_names)),),
                    node=warning_node,
                )

        _compare_missing_args(
            params_with_doc, "missing-param-doc", self.not_needed_param_in_docstring
        )

        for index, arg_name in enumerate(arguments_node.args):
            if arguments_node.annotations[index]:
                params_with_type.add(arg_name.name)

        _compare_missing_args(
            params_with_type, "missing-type-doc", not_needed_type_in_docstring
        )

        _compare_different_args(
            params_with_doc, "differing-param-doc", self.not_needed_param_in_docstring
        )
        _compare_different_args(
            params_with_type, "differing-type-doc", not_needed_type_in_docstring
        )
def check_arguments_in_docstring ( self , doc , arguments_node , warning_node , accept_no_param_doc = None ) : # Tolerate missing param or type declarations if there is a link to # another method carrying the same name. if not doc . doc : return if accept_no_param_doc is None : accept_no_param_doc = self . config . accept_no_param_doc tolerate_missing_params = doc . params_documented_elsewhere ( ) # Collect the function arguments. expected_argument_names = { arg . name for arg in arguments_node . args } expected_argument_names . update ( arg . name for arg in arguments_node . kwonlyargs ) not_needed_type_in_docstring = self . not_needed_param_in_docstring . copy ( ) if arguments_node . vararg is not None : expected_argument_names . add ( arguments_node . vararg ) not_needed_type_in_docstring . add ( arguments_node . vararg ) if arguments_node . kwarg is not None : expected_argument_names . add ( arguments_node . kwarg ) not_needed_type_in_docstring . add ( arguments_node . kwarg ) params_with_doc , params_with_type = doc . match_param_docs ( ) # Tolerate no parameter documentation at all. if not params_with_doc and not params_with_type and accept_no_param_doc : tolerate_missing_params = True def _compare_missing_args ( found_argument_names , message_id , not_needed_names ) : """Compare the found argument names with the expected ones and
            generate a message if there are arguments missing.

            :param set found_argument_names: argument names found in the
                docstring

            :param str message_id: pylint message id

            :param not_needed_names: names that may be omitted
            :type not_needed_names: set of str
            """ if not tolerate_missing_params : missing_argument_names = ( expected_argument_names - found_argument_names ) - not_needed_names if missing_argument_names : self . add_message ( message_id , args = ( ", " . join ( sorted ( missing_argument_names ) ) , ) , node = warning_node , ) def _compare_different_args ( found_argument_names , message_id , not_needed_names ) : """Compare the found argument names with the expected ones and
            generate a message if there are extra arguments found.

            :param set found_argument_names: argument names found in the
                docstring

            :param str message_id: pylint message id

            :param not_needed_names: names that may be omitted
            :type not_needed_names: set of str
            """ differing_argument_names = ( ( expected_argument_names ^ found_argument_names ) - not_needed_names - expected_argument_names ) if differing_argument_names : self . add_message ( message_id , args = ( ", " . join ( sorted ( differing_argument_names ) ) , ) , node = warning_node , ) _compare_missing_args ( params_with_doc , "missing-param-doc" , self . not_needed_param_in_docstring ) for index , arg_name in enumerate ( arguments_node . args ) : if arguments_node . annotations [ index ] : params_with_type . add ( arg_name . name ) _compare_missing_args ( params_with_type , "missing-type-doc" , not_needed_type_in_docstring ) _compare_different_args ( params_with_doc , "differing-param-doc" , self . not_needed_param_in_docstring ) _compare_different_args ( params_with_type , "differing-type-doc" , not_needed_type_in_docstring )
Check that all parameters in a function, method or class constructor
        on the one hand and the parameters mentioned in the parameter
        documentation (e.g. the Sphinx tags 'param' and 'type') on the other
        hand are consistent with each other.

        * Undocumented parameters except 'self' are noticed.
        * Undocumented parameter types except for 'self' and the ``*<args>``
          and ``**<kwargs>`` parameters are noticed.
        * Parameters mentioned in the parameter documentation that don't or no
          longer exist in the function parameter list are noticed.
        * If the text "For the parameters, see" or "For the other parameters,
          see" (ignoring additional whitespace) is mentioned in the docstring,
          missing parameter documentation is tolerated.
        * If there's no Sphinx style, Google style or NumPy style parameter
          documentation at all, i.e. ``:param`` is never mentioned etc., the
          checker assumes that the parameters are documented in another format
          and the absence is tolerated.

        :param doc: Docstring for the function, method or class.
        :type doc: str

        :param arguments_node: Arguments node for the function, method or
            class constructor.
        :type arguments_node: :class:`astroid.scoped_nodes.Arguments`

        :param warning_node: The node to assign the warnings to
        :type warning_node: :class:`astroid.scoped_nodes.Node`

        :param accept_no_param_doc: Whether or not to allow no parameters
            to be documented.
            If None then this value is read from the configuration.
        :type accept_no_param_doc: bool or None
Check that all parameters in a function method or class constructor on the one hand and the parameters mentioned in the parameter documentation ( e . g . the Sphinx tags param and type ) on the other hand are consistent with each other .