Decorate a function to be the completer function of commands.

    Arguments:
        commands: Names of command that should trigger this function object.

    ------------------------------
    Interface of completer methods:

        @completer('some-other_command')
        def complete_foo(self, args, text):
            '''
            Arguments:
                args: A list of arguments. The first token, i.e, the command
                    itself, is not included.
                text: The scope of text being replaced.

                A few examples, with '$' representing the shell prompt and
                '|' represents the cursor position:
                        $ |
                        $ history|
                            handled by the __driver_completer() method
                        $ history |
                            args = []
                            text = ''
                        $ history cle|
                            args = []
                            text = 'cle'
                        $ history clear |
                            args = ['clear']
                            text = ''

            Returns:
                A list of candidates. If no candidate was found, return
                either [] or None.
            '''
            pass

def completer(*commands):
    """Decorate a function to be the completer function of commands.

    Arguments:
        commands: Names of command that should trigger this function object.

    ------------------------------
    Interface of completer methods:

        @completer('some-other_command')
        def complete_foo(self, args, text):
            '''
            Arguments:
                args: A list of arguments. The first token, i.e, the command
                    itself, is not included.
                text: The scope of text being replaced.

                A few examples, with '$' representing the shell prompt and
                '|' represents the cursor position:
                        $ |
                        $ history|
                            handled by the __driver_completer() method
                        $ history |
                            args = []
                            text = ''
                        $ history cle|
                            args = []
                            text = 'cle'
                        $ history clear |
                            args = ['clear']
                            text = ''

            Returns:
                A list of candidates. If no candidate was found, return
                either [] or None.
            '''
            pass
    """
    def decorated_func(f):
        f.__complete_targets__ = list(commands)
        return f
    return decorated_func