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)
errors = list(parse_errors(ERRORS_IN))
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(
parse_tl(TLOBJECT_IN_CORE_TL, layer, invalid_bot_methods),
parse_tl(TLOBJECT_IN_TL, layer, invalid_bot_methods)))
parse_tl(TLOBJECT_IN_CORE_TL, layer, methods),
parse_tl(TLOBJECT_IN_TL, layer, methods)))
if not which:
which.extend(('tl', 'errors'))

View File

@ -7,7 +7,7 @@ import shutil
from collections import defaultdict
from ..docswriter import DocsWriter
from ..parsers import TLObject
from ..parsers import TLObject, Usability
from ..utils import snake_to_camel_case
CORE_TYPES = {
@ -138,8 +138,8 @@ def _generate_index(folder, original_paths, root,
docs.write_title(_get_relative_path(folder, root, folder=True).title())
if bots_index:
docs.write_text('These are the methods that you can use as a bot. '
'Click <a href="{}">here</a> to '
docs.write_text('These are the methods that you may be able to '
'use as a bot. Click <a href="{}">here</a> to '
'view them all.'.format(INDEX))
else:
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)
if tlobject.is_function:
docs.write_text('Bots <strong>can{}</strong> use this method. '
'<a href="#examples">See code examples.</a>'
.format("" if tlobject.bot_usable else "'t"))
if tlobject.is_function and tlobject.bot_usable:
if tlobject.usability == Usability.USER:
start = '<strong>Only users</strong> can'
elif tlobject.usability == Usability.BOT:
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
docs.write_code(tlobject)

View File

@ -1,3 +1,3 @@
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

View File

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

View File

@ -14,7 +14,8 @@ for i in range(77, 83):
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.
@ -24,6 +25,7 @@ class TLObject:
:param args: The arguments, if any, 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 usability: The usability for this method.
:param layer: The layer this TLObject belongs to.
"""
# The name can or not have a namespace
@ -36,7 +38,7 @@ class TLObject:
self.args = args
self.result = result
self.is_function = is_function
self.bot_usable = None
self.usability = usability
self.id = None
if object_id is None:
self.id = self.infer_id()