kuroko-lang/kuroko
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Various doc improvements

Browse Source
This commit is contained in:
K. Lange 2021-02-20 15:43:47 +09:00
parent 663de74695
commit 76d53eb198
5 changed files with 57 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/Doxyfile
View File

@ -28,7 +28,8 @@ HTML_COLORSTYLE_SAT = 200
# Doxygen will enable latex by default, so let's turn that off.
GENERATE_LATEX = NO
ALIASES += methodstart{4}="\htmlonly<\3 class=\"memtitle \4\" id=\"\1\"><span class=\"permalink\"><a href=\"#\1\">_</a></span>\2</\3><div class=\"memitem\"><div class=\"memdoc\">\endhtmlonly"
ALIASES += methodstart{4}="\anchor \1 \htmlonly<\3 class=\"memtitle \4\"><span class=\"permalink\"><a href=\"#\1\">_</a></span>\2</\3><div class=\"memitem\"><div class=\"memdoc\">\endhtmlonly"
ALIASES += methodstart{5}="\anchor \1 \htmlonly<\3 class=\"memtitle \4\"><span class=\"permalink\"><a href=\"#\1\">_</a></span>\2</\3><div class=\"memitem\"><div class=\"memproto\">\5</div><div class=\"memdoc\">\endhtmlonly"
ALIASES += methodend="\htmlonly</div></div>\endhtmlonly"
ALIASES += bsnote{1}="\htmlonly<div class=\"alert alert-warning\">\endhtmlonly\1\htmlonly</div>\endhtmlonly"

7
src/builtins.c
View File

@ -405,13 +405,16 @@ void _createAndBind_builtins(void) {
krk_finalizeClass(vm.baseClasses->propertyClass);
krk_makeClass(vm.builtins, &Helper, "Helper", vm.baseClasses->objectClass);
BIND_METHOD(Helper,__call__);
Helper->docstring = S("Special object that prints a helpful message when passed to @ref repr");
BIND_METHOD(Helper,__call__)->doc = "@arguments obj=None\nPrints the help documentation attached to @p obj or "
"starts the interactive help system.";
BIND_METHOD(Helper,__repr__);
krk_finalizeClass(Helper);
krk_attachNamedObject(&vm.builtins->fields, "help", (KrkObj*)krk_newInstance(Helper));
krk_makeClass(vm.builtins, &LicenseReader, "LicenseReader", vm.baseClasses->objectClass);
BIND_METHOD(LicenseReader,__call__);
LicenseReader->docstring = S("Special object that prints Kuroko's copyright information when passed to @ref repr");
BIND_METHOD(LicenseReader,__call__)->doc = "Print the full license statement.";
BIND_METHOD(LicenseReader,__repr__);
krk_finalizeClass(LicenseReader);
krk_attachNamedObject(&vm.builtins->fields, "license", (KrkObj*)krk_newInstance(LicenseReader));

5
src/obj_bytes.c
View File

@ -215,7 +215,10 @@ _corrupt:
_noexport
void _createAndBind_bytesClass(void) {
KrkClass * bytes = ADD_BASE_CLASS(vm.baseClasses->bytesClass, "bytes", vm.baseClasses->objectClass);
BIND_METHOD(bytes,__init__);
BIND_METHOD(bytes,__init__)->doc =
"@arguments iter=None\n"
"Creates a new @ref bytes object. If @p iter is provided, it should be a @ref tuple or @ref list "
"of integers within the range @c 0 and @c 255.";
BIND_METHOD(bytes,__repr__);
BIND_METHOD(bytes,__len__);
BIND_METHOD(bytes,__contains__);

29
src/threads.c
View File

@ -207,26 +207,37 @@ void _createAndBind_threadsMod(void) {
krk_attachNamedObject(&threadsModule->fields, "__name__", (KrkObj*)S("threading"));
krk_attachNamedValue(&threadsModule->fields, "__file__", NONE_VAL());
krk_attachNamedObject(&threadsModule->fields, "__doc__",
(KrkObj*)S("Methods for dealing with threads."));
(KrkObj*)S("Methods and classes for creating platform threads."));
BIND_FUNC(threadsModule, current_thread);
BIND_FUNC(threadsModule, current_thread)->doc = "@arguments \nReturns the @ref Thread object associated with the calling thread, if one exists.";
krk_makeClass(threadsModule, &ThreadError, "ThreadError", vm.exceptions->baseException);
ThreadError->docstring = S(
"Raised in various situations when an action on a thread is invalid."
);
krk_finalizeClass(ThreadError);
krk_makeClass(threadsModule, &Thread, "Thread", vm.baseClasses->objectClass);
Thread->docstring = S(
"Base class for building threaded execution contexts.\n\n"
"The @ref Thread class should be subclassed and the subclass should implement a @c run method."
);
Thread->allocSize = sizeof(struct Thread);
BIND_METHOD(Thread,start);
BIND_METHOD(Thread,join);
BIND_METHOD(Thread,is_alive);
BIND_PROP(Thread,tid);
BIND_METHOD(Thread,start)->doc = "Start the thread. A thread may only be started once.";
BIND_METHOD(Thread,join)->doc = "Join the thread. Does not return until the thread finishes.";
BIND_METHOD(Thread,is_alive)->doc = "Query the status of the thread.";
AS_NATIVE(BIND_PROP(Thread,tid)->method)->doc = "The platform-specific thread identifier, if available. Usually an integer.";
krk_finalizeClass(Thread);
krk_makeClass(threadsModule, &Lock, "Lock", vm.baseClasses->objectClass);
Lock->docstring = S(
"Represents an atomic mutex.\n\n"
"@ref Lock objects allow for exclusive access to a resource and can be used in a @c with block."
);
Lock->allocSize = sizeof(struct Lock);
BIND_METHOD(Lock,__init__);
BIND_METHOD(Lock,__enter__);
BIND_METHOD(Lock,__exit__);
BIND_METHOD(Lock,__init__)->doc = "Initialize a system mutex.";
BIND_METHOD(Lock,__enter__)->doc = "Acquire the lock.";
BIND_METHOD(Lock,__exit__)->doc = "Release the lock.";
BIND_METHOD(Lock,__repr__);
krk_finalizeClass(Lock);
}

36
tools/gendoc.krk
View File

@ -23,9 +23,17 @@ let blacklistedMethods = [
]
let specialMethods = {
'__contains__': lambda cls, args: f'{args} in {cls}',
'__init__': lambda cls, args: f'{cls}({args})',
'__get__': lambda cls, args: f'{cls}[{args}]',
'__contains__': lambda cls, args: f'{args or "<i>needle</i>"} <b>in</b> {cls}',
'__init__': lambda cls, args: f'let <i>x</i> = <b>{cls}</b>({args})',
'__get__': lambda cls, args: f'{cls}[{args or "<i>key</i>"}]',
'__delitem__': lambda cls, args: f'<b>del</b> {cls}[{args or "<i>key</i>"}]',
'__add__': lambda cls, args: f'{cls} + {args or "<i>other</i>"}',
'__len__': lambda cls, args: f'<b>len</b>({cls})',
'__call__': lambda cls, args: f'{cls}({args})',
'__iter__': lambda cls, args: f'<b>for</b> <i>x</i> <b>in</b> {cls}:',
'__eq__': lambda cls, args: f'{cls} == {args or "<i>other</i>"}',
'__lt__': lambda cls, args: f'{cls} &lt; {args or "<i>other</i>"}',
'__gt__': lambda cls, args: f'{cls} &gt; {args or "<i>other</i>"}',
}
class Pair():
@ -33,12 +41,19 @@ class Pair():
def __init__(left,right):
self.left = left
self.right = right
def __eq__(other):
if not isinstance(other,Pair): return False
return self.left == other.left
def __lt__(other):
if self.left == '__init__': return True
if self.left == '__init__' and other.left != '__init__': return True
if other.left == '__init__': return False
return self.left < other.left
def __gt__(other):
if self.left == '__init__': return False
if other.left == '__init__': return True
return self.left > other.left
def __repr__():
return f'Pair({self.left!r},{self.right!r})'
def __iter__():
let x = -1
def _():
@ -108,7 +123,7 @@ def getArgs(func):
let before, after = func.__doc__.split('@arguments ',1)
let line, rest = after.split('\n',1) if '\n' in after else (after,None)
return line.strip().replace(',','\\,')
return '...'
return ''
return '\\,'.join([x for x in func.__args__ if x != 'self'])
def functionDoc(func):
@ -139,15 +154,16 @@ def processModules(modules):
def outputFunction(name, func, prefix=None):
# Build the function signature
let args = '<i>' + getArgs(func) + '</i>'
let _args = getArgs(func)
let args = ('<i>' + _args + '</i>') if _args else ''
let body = functionDoc(func)
let formatted
let maybePrefix = prefix + '.' if prefix else ''
let formatted = maybePrefix + '<b>' + name + '</b>(' + args + ')'
let maybeDetail = ''
if prefix and name in specialMethods:
maybeDetail = ',' + formatted
formatted = specialMethods[name](prefix,args)
else:
formatted = maybePrefix + '<b>' + name + '</b>(' + args + ')'
print('\\methodstart{' + maybePrefix + name + ',' + formatted + ',' + ('h4,methodDef' if prefix else 'h3,functionDef') + '}')
print('\\methodstart{' + (maybePrefix + name).replace('.','_') + ',' + formatted + ',' + ('h4,methodDef' if prefix else 'h3,functionDef') + maybeDetail + '}')
if body: print(body)
print('\n\\methodend')
print('')