#!/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()
|
