xref: /aosp_15_r20/external/sl4a/Docs/generate_api_reference_md.py (revision 456ef56af69dcf0481dd36cc45216c4002d72fa3)

#!/usr/bin/env python
#
#  Copyright (C) 2016 Google, Inc.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at:
#
#  http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

import collections
import itertools
import os
import re
import subprocess

# Parsing states:
# STATE_INITIAL: looking for rpc or function defintion
# STATE_RPC_DECORATOR: in the middle of a multi-line rpc definition
# STATE_FUNCTION_DECORATOR: in the middle of a multi-line function definition
# STATE_COMPLETE: done parsing a function
STATE_INITIAL = 1
STATE_RPC_DECORATOR = 2
STATE_FUNCTION_DEFINITION = 3
STATE_COMPLETE = 4

# RE to match key=value tuples with matching quoting on value.
KEY_VAL_RE = re.compile(r'''
        (?P<key>\w+)\s*=\s* # Key consists of only alphanumerics
        (?P<quote>["']?)    # Optional quote character.
        (?P<value>.*?)      # Value is a non greedy match
        (?P=quote)          # Closing quote equals the first.
        ($|,)               # Entry ends with comma or end of string
    ''', re.VERBOSE)

# RE to match a function definition and extract out the function name.
FUNC_RE = re.compile(r'.+\s+(\w+)\s*\(.*')


class Function(object):
    """Represents a RPC-exported function."""

    def __init__(self, rpc_def, func_def):
        """Constructs a function object given its RPC and function signature."""
        self._function = ''
        self._signature = ''
        self._description = ''
        self._returns = ''

        self._ParseRpcDefinition(rpc_def)
        self._ParseFunctionDefinition(func_def)

    def _ParseRpcDefinition(self, s):
        """Parse RPC definition."""
        # collapse string concatenation
        s = s.replace('" + "', '')
        s = s.strip('()')
        for m in KEY_VAL_RE.finditer(s):
            if m.group('key') == 'description':
                self._description = m.group('value')
            if m.group('key') == 'returns':
                self._returns = m.group('value')

    def _ParseFunctionDefinition(self, s):
        """Parse function definition."""
        # Remove some keywords we don't care about.
        s = s.replace('public ', '')
        s = s.replace('synchronized ', '')
        # Remove any throw specifications.
        s = re.sub('\s+throws.*', '', s)
        s = s.strip('{')
        # Remove all the RPC parameter annotations.
        s = s.replace('@RpcOptional ', '')
        s = s.replace('@RpcOptional() ', '')
        s = re.sub('@RpcParameter\s*\(.+?\)\s+', '', s)
        s = re.sub('@RpcDefault\s*\(.+?\)\s+', '', s)
        m = FUNC_RE.match(s)
        if m:
            self._function = m.group(1)
        self._signature = s.strip()

    @property
    def function(self):
        return self._function

    @property
    def signature(self):
        return self._signature

    @property
    def description(self):
        return self._description

    @property
    def returns(self):
        return self._returns


class DocGenerator(object):
    """Documentation genereator."""

    def __init__(self, basepath):
        """Construct based on all the *Facade.java files in the given basepath."""
        self._functions = collections.defaultdict(list)

        for path, dirs, files in os.walk(basepath):
            for f in files:
                if f.endswith('Facade.java'):
                    self._Parse(os.path.join(path, f))

    def _Parse(self, filename):
        """Parser state machine for a single file."""
        state = STATE_INITIAL
        self._current_rpc = ''
        self._current_function = ''

        with open(filename, 'r') as f:
            for line in f.readlines():
                line = line.strip()
                if state == STATE_INITIAL:
                    state = self._ParseLineInitial(line)
                elif state == STATE_RPC_DECORATOR:
                    state = self._ParseLineRpcDecorator(line)
                elif state == STATE_FUNCTION_DEFINITION:
                    state = self._ParseLineFunctionDefinition(line)

                if state == STATE_COMPLETE:
                    self._EmitFunction(filename)
                    state = STATE_INITIAL

    def _ParseLineInitial(self, line):
        """Parse a line while in STATE_INITIAL."""
        if line.startswith('@Rpc('):
            self._current_rpc = line[4:]
            if not line.endswith(')'):
                # Multi-line RPC definition
                return STATE_RPC_DECORATOR
        elif line.startswith('public'):
            self._current_function = line
            if not line.endswith('{'):
                # Multi-line function definition
                return STATE_FUNCTION_DEFINITION
            else:
                return STATE_COMPLETE
        return STATE_INITIAL

    def _ParseLineRpcDecorator(self, line):
        """Parse a line while in STATE_RPC_DECORATOR."""
        self._current_rpc += ' ' + line
        if line.endswith(')'):
            # Done with RPC definition
            return STATE_INITIAL
        else:
            # Multi-line RPC definition
            return STATE_RPC_DECORATOR

    def _ParseLineFunctionDefinition(self, line):
        """Parse a line while in STATE_FUNCTION_DEFINITION."""
        self._current_function += ' ' + line
        if line.endswith('{'):
            # Done with function definition
            return STATE_COMPLETE
        else:
            # Multi-line function definition
            return STATE_FUNCTION_DEFINITION

    def _EmitFunction(self, filename):
        """Store a function definition from the current parse state."""
        if self._current_rpc and self._current_function:
            module = os.path.basename(filename)[0:-5]
            f = Function(self._current_rpc, self._current_function)
            if f.function:
                self._functions[module].append(f)

        self._current_rpc = None
        self._current_function = None

    def WriteOutput(self, filename):
        git_rev = None
        try:
            git_rev = subprocess.check_output('git rev-parse HEAD',
                                              shell=True).strip()
        except subprocess.CalledProcessError as e:
            # Getting the commit ID is optional; we continue if we cannot get it
            pass

        with open(filename, 'w') as f:
            if git_rev:
                f.write('Generated at commit `%s`\n\n' % git_rev)
            # Write table of contents
            for module in sorted(self._functions.keys()):
                f.write('**%s**\n\n' % module)
                for func in self._functions[module]:
                    f.write('  * [%s](#%s)\n' %
                            (func.function, func.function.lower()))
                f.write('\n')

            f.write('# Method descriptions\n\n')
            for func in itertools.chain.from_iterable(
                    self._functions.values()):
                f.write('## %s\n\n' % func.function)
                f.write('```\n')
                f.write('%s\n\n' % func.signature)
                f.write('%s\n' % func.description)
                if func.returns:
                    if func.returns.lower().startswith('return'):
                        f.write('\n%s\n' % func.returns)
                    else:
                        f.write('\nReturns %s\n' % func.returns)
                f.write('```\n\n')

# Main
basepath = os.path.abspath(os.path.join(os.path.dirname(
    os.path.realpath(__file__)), '..'))
g = DocGenerator(basepath)
g.WriteOutput(os.path.join(basepath, 'Docs/ApiReference.md'))