@@ Docf Version 1.0
@create Docf Object
@set Docf Object=!no_command
@power Docf Object = See_All
&CMD_DOCF Docf Object=$^docf(f)? ([^/]+)$:@assert setr(0,locate(%#,%2,X*))={@pemit %#=Can't find the object you wanted.};@assert visible(%#,%q0)={@pemit %#=You can't read what you can't see.};@pemit %#=u(fun_document_all,%q0,%1)
@set Docf Object/CMD_DOCF=regexp
&CMD_DOCF_FLAGS Docf Object=$docf/flags:@pemit %#=Available flags:%r[u(fun_document_flags)]
&CMD_DOCF_HELP Docf Object=$docf/help:@pemit %#=u(static`help)
&CMD_DOCF_ONE Docf Object=$^docf(f)? ([^/]+)/(.*)$:@assert setr(0,locate(%#,%2,X*))={@pemit %#=Can't find the object you wanted.};@assert visible(%#,%q0/%3)={@pemit %#=You can't read what you can't see.};@pemit %#=u(fun_document,%q0,%3,%1)
@set Docf Object/CMD_DOCF_ONE=regexp
&CMD_DOCF_SYNTAX Docf Object=$docf/syntax:@pemit %#=u(static`syntax)
@DESCRIBE Docf Object=u(static`help)%r(This text is also available as docf/help.)
&FLAG Docf Object=Flags are stored under this tree.
&FLAG`FUNC Docf Object=Purely functional.
&FLAG`FUNC`DESC Docf Object=Indicates the function is considered purely functional.
&FLAG`NODIRECT Docf Object=Not meant to be called directly.[if(%0,%bCall `[ansi(v(reference),%0)]' instead.)]
&FLAG`NODIRECT`DESC Docf Object=Indicates this function probably shouldn't be called directly. Argument: Which function to use instead.
&FLAG`QREG Docf Object=Uses q registers[if(strlen(%0),: [edit(%0,:,\,%b)],.)]
&FLAG`QREG`DESC Docf Object=Indicates the function either sets or uses q registers that can affect it or outside code. Arguments: which registers are used.
&FLAG`R Docf Object==> [if(strmatch(%0,*:*),rest(%0,:) \([art(first(%0,:))] [first(%0,:)]\),%0)]
&FLAG`SFX Docf Object=Has side effects.
&FLAG`SFX`DESC Docf Object=Indicates the function has side effects.
&FLAG`USE Docf Object=Used as the attr for[if(strlen(%0),%b%0().,.. something. Apparently.)]
&FLAG`USE`DESC Docf Object=Indicates the function is used as the variable for map() or fold() or the like. Argument: which function it's meant to be used with.
&FOLD_ARGLIST Docf Object=[if(comp(%1,*),%0\,%b[if(first(%0,|),\[%1\],<%1>)],*%0)]
&FOLD_ARGLIST`CC Docf Object=current:next r:string:arglist_with_next_added func use:fold nodirect:fun_parse_arglist
&FOLD_ARGLIST`DOC Docf Object=Adds argument NEXT to the partial list CURRENT, decorated as a mandatory or optional argument as appropriate. An argument of '*' marks further arguments as optional.
&FOLD_DECORATE Docf Object=if(comp(%1,*),if(regmatch(%0,\\b([ucstr(%1)])\\b),regedit(%0,\\b([ucstr(%1)])\\b,if(first(%0,|),strcat(ansi(h,\[),lcstr($1),ansi(h,\])),strcat(ansi(h,<),lcstr($1),ansi(h,>)))),%0 \(Variable %1 undocumented.\)),*%0)
&FOLD_DECORATE`CC Docf Object=text:varname r:string:text_with_variable_decorated func use:fold nodirect:fun_decorate
&FOLD_DECORATE`DOC Docf Object=Decorate VARNAME as a variable within TEXT. Pass * as the variable name to treat remaining variables as optional.
&FUN_DECORATE Docf Object=u(fun_decorate_refs,rest(fold(fold_decorate,%1,|%0,:),|))
&FUN_DECORATE_REFS Docf Object=regeditall(%0,`(\[\\w<>`_-\]+)',`[ansi(v(static`reference),$1)]')
&FUN_DECORATE_REFS`CC Docf Object=text r:string:text_with_refs_decorated func
&FUN_DECORATE_REFS`DOC Docf Object=Decorates references to other attrs in TEXT. Specifically, any text between ` and ' that looks like an attribute name. Uses the ansi specification in `reference' but it's considered a constant.
&FUN_DECORATE`CC Docf Object=text:arglist r:string:decorated_text func
&FUN_DECORATE`DOC Docf Object=Decorate TEXT so that arguments in ARGLIST are marked as optional or mandatory inside the text. Arguments that don't appear to be documented are warned about at the end of the text. Also calls `fun_decorate_refs' to decorate references to other attributes.
&FUN_DOCUMENT Docf Object=ifelse(hasattr(%0,%1`cc),u(fun_parse_cc,lcstr(%1),xget(%0,%1`cc)),Function has no calling convention defined.)[if(%2,%r[if(hasattr(%0,%1`doc),u(fun_decorate,u(%0/%1`doc),first(xget(%0,%1`cc))),Function has no docstring.)])]
&FUN_DOCUMENT_ALL Docf Object=map(#lambda/u(fun_document,[decompose(%0)],%%0,[decompose(%1)]),edit(lattr(%0/**`cc),`CC,),%b,%r%r)
&FUN_DOCUMENT_ALL`CC Docf Object=object:*:all r:string:documentation
&FUN_DOCUMENT_ALL`DOC Docf Object=Return documentation for all ufuns with at least a `cc on OBJECT. If ALL is true, show docstrings as well. Essentially calls `fun_document' on everything meaningful.
&FUN_DOCUMENT_FLAGS Docf Object=map(#lambda/strcat(* %%0,ifelse(hasattr(me,flag`%%0`desc),cat(:,v(flag`%%0`desc)),%%bis not documented.)),setdiff(lcstr(edit(lattr(me/flag`*),FLAG`,)),v(static`ignored_flags)),%b,%r)
&FUN_DOCUMENT_FLAGS`CC Docf Object=* r:string:flag_descriptions
&FUN_DOCUMENT_FLAGS`DOC Docf Object=Returns all flags that aren't in `static`ignored_flags', and a description of what they are for, if they are documented.
&FUN_DOCUMENT`CC Docf Object=object:attr:*:full r:string:documentation
&FUN_DOCUMENT`DOC Docf Object=Get the documentation of the ufun in OBJECT/ATTR. If FULL, output the docstring as well as the calling convention.
&FUN_PARSE_ARGLIST Docf Object=u\([rest(fold(fold_arglist,%1,|%0,:),|)]\)
&FUN_PARSE_ARGLIST`CC Docf Object=function:arglist r:string:calling_convention func
&FUN_PARSE_ARGLIST`DOC Docf Object=Returns a description of how to call FUNCTION. ARGLIST is either a list of argument names separated by colons, with an 'argument' of * to specify that remaining arguments are optional, or a single '*' to indicate the function doesn't take arguments at all.
&FUN_PARSE_CC Docf Object=Call: [u(fun_parse_arglist,%0,first(%1))][if(setr(0,u(fun_parse_flags,rest(%1))),u(static`sep)%q0)]
&FUN_PARSE_CC`CC Docf Object=function:cc r:string:calling_convention qreg:0
&FUN_PARSE_CC`DOC Docf Object=Returns all quick reference info about FUNCTION. CC will most likely come from a `cc attr, and will consist of an arglist (parsed by `fun_parse_arglist') and optionally flags (parsed by `fun_parse_flags').
&FUN_PARSE_FLAGS Docf Object=map(#lambda/udefault(strcat(flag`,first(%%0,:)),%%0?,rest(%%0,:)),%0,%b,u(static`sep))
&FUN_PARSE_FLAGS`CC Docf Object=flaglist r:string:flag_meanings
&FUN_PARSE_FLAGS`DOC Docf Object=Given a list of 'flag' or 'flag:argument' in FLAGLIST, returns a text version of what the flags say about the function. Individual flags are defined in flag`<name>. Note that r:, used for return values, is technically a flag, though stylistically it should be the first flag in the list.
&STATIC Docf Object=Tree for assorted text that probably doesn't change often.
&STATIC`HELP Docf Object=[align(10 40,Commands:, docf <obj>\[/<attr>\]%rdocff <obj>\[/<attr>\])]%r%rBoth commands display ufun documentation for the given object, or just for the given attr. docf gives just information about the function's arguments, return value, and similar as a quick reference how the function works.%rdocff (the second f signifying 'full') also displays the function's docstring, if available.%r%rMandatory arguments are marked with <arg> while optional arguments are marked with \[arg\].%r%rFor a function in an attr named `[ansi(v(static`reference),fun_foo)]' the following attributes will provide documentation data:%r[align(4 70,,{fun_foo`cc: A short string with the calling info. This is the minimum required for a function to be considered documented.%rfun_foo`doc: A more detailed docstring describing in human language (with a bit of markup) how the function works.})]%r%rSee docf/syntax for details on how to write your own documentation. See docf/flags for a quick overview of the available flags.
&STATIC`IGNORED_FLAGS Docf Object=r
&STATIC`REFERENCE Docf Object=u
&STATIC`SEP Docf Object=%r%b%b
&STATIC`SYNTAX Docf Object=The syntax for a `cc attribute is as follows:%r%r%t<arg1>:<arg2>:<argN> \[r:\[<returntype>:\]<returninfo>\] \[flags\]%r%rArguments are separated by colons. Use an argument of '*' to indicate remaining arguments are optional. For example: 'message:*:target' means there is one mandatory argument 'message' and one optional argument 'target'. If the function takes no arguments at all, specify '*'.%r%tThe return info is optional, as is the type if you supply any info at all. It should give a quick summary of the ufun's return value, such as 'r:dbref:victim'.%r%tFlags give additional info about the function. If a flag takes arguments, they can be supplied as '<flagname>:<arg1>:<arg2>:<argN>'. For most flags the arguments are optional. The following flags are currently available:%r%r[u(fun_document_flags)]%r%rThe syntax for a `doc attribute is a text description of how the function works. Refer to each function argument once in ALL_CAPS. A warning will be added for each undocumented argument. Write references to other functions or variabled `like_this'. They will be formatted `[ansi(v(static`reference),like_this)]'.