Clarify who can use methods in the documentation

This commit is contained in:
Lonami Exo 2018-12-03 16:17:37 +01:00
parent e4cfd964d5
commit 50b77d881d
5 changed files with 40 additions and 21 deletions

View File

@ -63,11 +63,10 @@ def generate(which):
layer = find_layer(TLOBJECT_IN_TL) layer = find_layer(TLOBJECT_IN_TL)
errors = list(parse_errors(ERRORS_IN)) errors = list(parse_errors(ERRORS_IN))
methods = list(parse_methods(METHODS_IN, {e.str_code: e for e in errors})) methods = list(parse_methods(METHODS_IN, {e.str_code: e for e in errors}))
invalid_bot_methods = {m.name for m in methods if m.usability == 'user'}
tlobjects = list(itertools.chain( tlobjects = list(itertools.chain(
parse_tl(TLOBJECT_IN_CORE_TL, layer, invalid_bot_methods), parse_tl(TLOBJECT_IN_CORE_TL, layer, methods),
parse_tl(TLOBJECT_IN_TL, layer, invalid_bot_methods))) parse_tl(TLOBJECT_IN_TL, layer, methods)))
if not which: if not which:
which.extend(('tl', 'errors')) which.extend(('tl', 'errors'))

View File

@ -7,7 +7,7 @@ import shutil
from collections import defaultdict from collections import defaultdict
from ..docswriter import DocsWriter from ..docswriter import DocsWriter
from ..parsers import TLObject from ..parsers import TLObject, Usability
from ..utils import snake_to_camel_case from ..utils import snake_to_camel_case
CORE_TYPES = { CORE_TYPES = {
@ -138,8 +138,8 @@ def _generate_index(folder, original_paths, root,
docs.write_title(_get_relative_path(folder, root, folder=True).title()) docs.write_title(_get_relative_path(folder, root, folder=True).title())
if bots_index: if bots_index:
docs.write_text('These are the methods that you can use as a bot. ' docs.write_text('These are the methods that you may be able to '
'Click <a href="{}">here</a> to ' 'use as a bot. Click <a href="{}">here</a> to '
'view them all.'.format(INDEX)) 'view them all.'.format(INDEX))
else: else:
docs.write_text('Click <a href="{}">here</a> to view the methods ' docs.write_text('Click <a href="{}">here</a> to view the methods '
@ -289,11 +289,21 @@ def _write_html_pages(tlobjects, methods, layer, input_res, output_dir):
docs.write_title(tlobject.class_name) docs.write_title(tlobject.class_name)
if tlobject.is_function: if tlobject.is_function:
docs.write_text('Bots <strong>can{}</strong> use this method. ' if tlobject.usability == Usability.USER:
'<a href="#examples">See code examples.</a>' start = '<strong>Only users</strong> can'
.format("" if tlobject.bot_usable else "'t")) elif tlobject.usability == Usability.BOT:
if tlobject.is_function and tlobject.bot_usable:
bot_docs_paths.append(filename) bot_docs_paths.append(filename)
start = '<strong>Only bots</strong> can'
elif tlobject.usability == Usability.BOTH:
bot_docs_paths.append(filename)
start = '<strong>Both users and bots</strong> can'
else:
bot_docs_paths.append(filename)
start = \
'Both users and bots <strong>may</strong> be able to'
docs.write_text('{} use this method. <a href="#examples">'
'See code examples.</a>'.format(start))
# Write the code definition for this TLObject # Write the code definition for this TLObject
docs.write_code(tlobject) docs.write_code(tlobject)

View File

@ -1,3 +1,3 @@
from .errors import Error, parse_errors from .errors import Error, parse_errors
from .methods import MethodInfo, parse_methods from .methods import MethodInfo, Usability, parse_methods
from .tlobject import TLObject, parse_tl, find_layer from .tlobject import TLObject, parse_tl, find_layer

View File

@ -3,9 +3,10 @@ import re
from .tlarg import TLArg from .tlarg import TLArg
from .tlobject import TLObject from .tlobject import TLObject
from ..methods import Usability
def _from_line(line, is_function, layer): def _from_line(line, is_function, method_info, layer):
match = re.match( match = re.match(
r'^([\w.]+)' # 'name' r'^([\w.]+)' # 'name'
r'(?:#([0-9a-fA-F]+))?' # '#optionalcode' r'(?:#([0-9a-fA-F]+))?' # '#optionalcode'
@ -26,27 +27,33 @@ def _from_line(line, is_function, layer):
r'}?', r'}?',
line line
) )
name = match.group(1)
if name in method_info:
usability = method_info[name].usability
else:
usability = Usability.UNKNOWN
return TLObject( return TLObject(
fullname=match.group(1), fullname=name,
object_id=match.group(2), object_id=match.group(2),
result=match.group(3), result=match.group(3),
is_function=is_function, is_function=is_function,
layer=layer, layer=layer,
usability=usability,
args=[TLArg(name, arg_type, brace != '') args=[TLArg(name, arg_type, brace != '')
for brace, name, arg_type in args_match] for brace, name, arg_type in args_match]
) )
def parse_tl(file_path, layer, invalid_bot_methods=None): def parse_tl(file_path, layer, methods=None):
""" """
This method yields TLObjects from a given .tl file. This method yields TLObjects from a given .tl file.
Note that the file is parsed completely before the function yields Note that the file is parsed completely before the function yields
because references to other objects may appear later in the file. because references to other objects may appear later in the file.
""" """
if invalid_bot_methods is None: method_info = {m.name: m for m in (methods or [])}
invalid_bot_methods = set()
obj_all = [] obj_all = []
obj_by_name = {} obj_by_name = {}
obj_by_type = collections.defaultdict(list) obj_by_type = collections.defaultdict(list)
@ -68,8 +75,9 @@ def parse_tl(file_path, layer, invalid_bot_methods=None):
continue continue
try: try:
result = _from_line(line, is_function, layer=layer) result = _from_line(
result.bot_usable = result.fullname not in invalid_bot_methods line, is_function, method_info, layer=layer)
obj_all.append(result) obj_all.append(result)
if not result.is_function: if not result.is_function:
obj_by_name[result.fullname] = result obj_by_name[result.fullname] = result

View File

@ -14,7 +14,8 @@ for i in range(77, 83):
class TLObject: class TLObject:
def __init__(self, fullname, object_id, args, result, is_function, layer): def __init__(self, fullname, object_id, args, result,
is_function, usability, layer):
""" """
Initializes a new TLObject, given its properties. Initializes a new TLObject, given its properties.
@ -24,6 +25,7 @@ class TLObject:
:param args: The arguments, if any, of the TL object :param args: The arguments, if any, of the TL object
:param result: The result type of the TL object :param result: The result type of the TL object
:param is_function: Is the object a function or a type? :param is_function: Is the object a function or a type?
:param usability: The usability for this method.
:param layer: The layer this TLObject belongs to. :param layer: The layer this TLObject belongs to.
""" """
# The name can or not have a namespace # The name can or not have a namespace
@ -36,7 +38,7 @@ class TLObject:
self.args = args self.args = args
self.result = result self.result = result
self.is_function = is_function self.is_function = is_function
self.bot_usable = None self.usability = usability
self.id = None self.id = None
if object_id is None: if object_id is None:
self.id = self.infer_id() self.id = self.infer_id()