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

#!/usr/bin/env python
#
#  Copyright (C) 2018 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 os
import re

# Matches a JavaDoc comment followed by an @Rpc annotation.
import subprocess

"""A regex that captures the JavaDoc comment and function signature."""
JAVADOC_RPC_REGEX = re.compile(
    # Capture the entire comment string.
    r'(?P<comment>/\*\*(?:(?!/\*\*).)*?\*/)(?:(?:(?!\*/).)*?)\s*'
    # Find at least one @Rpc Annotation
    r'(?:@\w+\s*)*?(?:@Rpc.*?\s*)(?:@\w+\s*)*?'
    # Capture the function signature, ignoring the throws statement
    # (the throws information will be pulled from the comment).
    r'(?P<function_signature>.*?)(?:throws.*?)?{',
    flags=re.MULTILINE | re.DOTALL)

"""
Captures javadoc "frills" like the ones found below:

/**
  *
  */

/** */

"""
CAPTURE_JAVADOC_FRILLS = re.compile(
    r'(^\s*(/\*\*$|/\*\* |\*($| ))|\s*\*/\s*$)',
    re.MULTILINE)

"""A regex to capture the individual pieces of the function signature."""
CAPTURE_FUNCTION_SIGNATURE = re.compile(
    # Capture any non-static function
    r'(public|private)'
    # Allow synchronized and @Annotations()
    r'[( synchronized)(@\w+\(.*?\)?)]*?'
    # Return Type (Allow n-number of generics and arrays)
    r'(?P<return_type>\w+(?:[\[\]<>\w ,]*?)?)\s+'
    # Capture functionName
    r'(?P<function_name>\w*)\s*'
    # Capture anything enclosed in parens
    r'\((?P<parameters>.*)\)',
    re.MULTILINE | re.DOTALL)

"""Matches a parameter and its RPC annotations."""
CAPTURE_PARAMETER = re.compile(
    r'(?:'
    r'(?P<optional>@RpcOptional\s+)?'
    r'(?P<rpc_param>@RpcParameter\(.*?\)\s*)?'
    r'(?P<default>@RpcDefault\((?P<default_value>.*)\)\s*)?'
    r')*'
    r'(?P<param_type>\w+)\s+(?P<param_name>\w+)',
    flags=re.MULTILINE | re.DOTALL)


class Facade(object):
    """A class representing a Facade.

    Attributes:
        path: the path the facade is located at.
        directory: the
    """

    def __init__(self, path):
        self.path = path
        self.directory = os.path.dirname(self.path)
        # -5 removes the '.java' file extension
        self.name = path[path.rfind('/') + 1:-5]
        self.rpcs = list()


def main():
    basepath = os.path.abspath(os.path.join(os.path.dirname(
        os.path.realpath(__file__)), '..'))

    facades = list()

    for path, dirs, files in os.walk(basepath):
        for file_name in files:
            if file_name.endswith('Facade.java'):
                facades.append(parse_facade_file(os.path.join(path, file_name)))

    basepath = os.path.abspath(os.path.join(os.path.dirname(
        os.path.realpath(__file__)), '..'))
    write_output(facades, os.path.join(basepath, 'Docs/ApiReference.md'))


def write_output(facades, output_path):
    facades = sorted(facades, key=lambda x: x.directory)

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

    with open(output_path, 'w') as fd:
        if git_rev:
            fd.write('Generated at commit `%s`\n\n' % git_rev)
        fd.write('# Facade Groups')
        prev_directory = ''
        for facade in facades:
            if facade.directory != prev_directory:
                fd.write('\n\n## %s\n\n' % facade.directory[
                                           facade.directory.rfind('/') + 1:])
                prev_directory = facade.directory
            fd.write('  * [%s](#%s)\n' % (facade.name, facade.name.lower()))

        fd.write('\n# Facades\n\n')
        for facade in facades:
            fd.write('\n## %s' % facade.name)
            for rpc in facade.rpcs:
                fd.write('\n\n### %s\n\n' % rpc.name)
                fd.write('%s\n' % rpc)


def parse_facade_file(file_path):
    """Parses a .*Facade.java file and represents it as a Facade object"""
    facade = Facade(file_path)
    with open(file_path, 'r') as content_file:
        content = content_file.read()
        matches = re.findall(JAVADOC_RPC_REGEX, content)
        for match in matches:
            rpc_function = DocumentedFunction(
                match[0].replace('\\n', '\n'),  # match[0]: JavaDoc comment
                match[1].replace('\\n', '\n'))  # match[1]: function signature
            facade.rpcs.append(rpc_function)
    facade.rpcs.sort(key=lambda rpc: rpc.name)
    return facade


class DefaultValue(object):
    """An object representation of a default value.

    Functions as Optional in Java, or a pointer in C++.

    Attributes:
        value: the default value
    """
    def __init__(self, default_value=None):
        self.value = default_value


class DocumentedValue(object):
    def __init__(self):
        """Creates an empty DocumentedValue object."""
        self.type = 'void'
        self.name = None
        self.description = None
        self.default_value = None

    def set_type(self, param_type):
        self.type = param_type
        return self

    def set_name(self, name):
        self.name = name
        return self

    def set_description(self, description):
        self.description = description
        return self

    def set_default_value(self, default_value):
        self.default_value = default_value
        return self

    def __str__(self):
        if self.name is None:
            return self.description
        if self.default_value is None:
            return '%s: %s' % (self.name, self.description)
        else:
            return '%s: %s (default: %s)' % (self.name, self.description,
                                             self.default_value.value)


class DocumentedFunction(object):
    """A combination of all function documentation into a single object.

    Attributes:
        _description: A string that describes the function.
        _parameters: A dictionary of {parameter name: DocumentedValue object}
        _return: a DocumentedValue with information on the returned value.
        _throws: A dictionary of {throw type (str): DocumentedValue object}

    """
    def __init__(self, comment, function_signature):
        self._name = None
        self._description = None
        self._parameters = {}
        self._return = DocumentedValue()
        self._throws = {}

        self._parse_comment(comment)
        self._parse_function_signature(function_signature)

    @property
    def name(self):
        return self._name

    def _parse_comment(self, comment):
        """Parses a JavaDoc comment into DocumentedFunction attributes."""
        comment = str(re.sub(CAPTURE_JAVADOC_FRILLS, '', comment))
        tag = 'description'
        tag_data = ''
        for line in comment.split('\n'):
            line.strip()
            if line.startswith('@'):
                self._finalize_tag(tag, tag_data)
                tag_end_index = line.find(' ')
                tag = line[1:tag_end_index]
                tag_data = line[tag_end_index + 1:]
            else:
                if not tag_data:
                    whitespace_char = ''
                elif (line.startswith(' ')
                      or tag_data.endswith('\n')
                      or line == ''):
                    whitespace_char = '\n'
                else:
                    whitespace_char = ' '
                tag_data = '%s%s%s' % (tag_data, whitespace_char, line)
        self._finalize_tag(tag, tag_data.strip())

    def __str__(self):
        params_signature = ', '.join(['%s %s' % (param.type, param.name)
                                      for param in self._parameters.values()])
        params_description = '\n    '.join(['%s: %s' % (param.name,
                                                        param.description)
                                            for param in
                                            self._parameters.values()])
        if params_description:
            params_description = ('\n**Parameters:**\n\n    %s\n' %
                                  params_description)
        return_description = '\n' if self._return else ''
        if self._return:
            return_description += ('**Returns:**\n\n    %s' %
                                   self._return.description)
        return (
            # ReturnType functionName(Parameters)
            '%s %s(%s)\n\n'
            # Description
            '%s\n'
            # Params & Return
            '%s%s' % (self._return.type, self._name,
                      params_signature, self._description,
                      params_description, return_description)).strip()

    def _parse_function_signature(self, function_signature):
        """Parses the function signature into DocumentedFunction attributes."""
        header_match = re.search(CAPTURE_FUNCTION_SIGNATURE, function_signature)
        self._name = header_match.group('function_name')
        self._return.set_type(header_match.group('return_type'))

        for match in re.finditer(CAPTURE_PARAMETER,
                                 header_match.group('parameters')):
            param_name = match.group('param_name')
            param_type = match.group('param_type')
            if match.group('default_value'):
                default = DefaultValue(match.group('default_value'))
            elif match.group('optional'):
                default = DefaultValue(None)
            else:
                default = None

            if param_name in self._parameters:
                param = self._parameters[param_name]
            else:
                param = DocumentedValue()
            param.set_type(param_type)
            param.set_name(param_name)
            param.set_default_value(default)

    def _finalize_tag(self, tag, tag_data):
        """Finalize the JavaDoc @tag by adding it to the correct field."""
        name = tag_data[:tag_data.find(' ')]
        description = tag_data[tag_data.find(' ') + 1:].strip()
        if tag == 'description':
            self._description = tag_data
        elif tag == 'param':
            if name in self._parameters:
                param = self._parameters[name]
            else:
                param = DocumentedValue().set_name(name)
                self._parameters[name] = param
            param.set_description(description)
        elif tag == 'return':
            self._return.set_description(tag_data)
        elif tag == 'throws':
            new_throws = DocumentedValue().set_name(name)
            new_throws.set_description(description)
            self._throws[name] = new_throws


if __name__ == '__main__':
    main()