diff options
author | Giovanni Campagna <gcampagna@src.gnome.org> | 2014-02-19 16:19:53 +0100 |
---|---|---|
committer | Giovanni Campagna <gcampagna@src.gnome.org> | 2014-02-20 02:07:48 +0100 |
commit | 75d25b7f47542aa003c92ce576b6e82bae66aec9 (patch) | |
tree | fe44b2083492e76f8bda7d903db169530dcba2b4 /giscanner/doctemplates/Gjs | |
parent | bd4608b6c761209bca8362bd5524e4dbe781e532 (diff) | |
download | gobject-introspection-75d25b7f47542aa003c92ce576b6e82bae66aec9.tar.gz |
doctool: improve Gjs documentation
- Add documentation for structures, fields, constants and
callbacks
- Improve the synopsis for interfaces to have prerequisites
and known implementations
- Respect gjs constraints for field writability
- Format in and out parameters for callables according to GJS
conventions
- Format property names according to the GJS API
- Show boxed constructors according to how they can be used
in the gjs API
https://bugzilla.gnome.org/show_bug.cgi?id=724735
Diffstat (limited to 'giscanner/doctemplates/Gjs')
-rw-r--r-- | giscanner/doctemplates/Gjs/callback.tmpl | 27 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/class.tmpl | 11 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/field.tmpl | 9 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/function.tmpl | 23 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/interface.tmpl | 17 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/property.tmpl | 7 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/signal.tmpl | 19 | ||||
-rw-r--r-- | giscanner/doctemplates/Gjs/vfunc.tmpl | 14 |
8 files changed, 91 insertions, 36 deletions
diff --git a/giscanner/doctemplates/Gjs/callback.tmpl b/giscanner/doctemplates/Gjs/callback.tmpl new file mode 100644 index 00000000..d7b97794 --- /dev/null +++ b/giscanner/doctemplates/Gjs/callback.tmpl @@ -0,0 +1,27 @@ +<%inherit file="/base.tmpl"/> +<%block name="synopsis"> + <synopsis><code mime="text/x-gjs"> +function on${node.name}(\ +${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\ +): ${formatter.format_out_parameters(node)} { +} + </code></synopsis></%block> +<%block name="details"> +% if formatter.has_any_parameters(node): +<terms> +% for arg in formatter.get_in_parameters(node): +<item> +<title><code>${arg.argname}</code></title> +${formatter.format(node, arg.doc)} +</item> +% endfor +% for arg in formatter.get_out_parameters(node): +<item> +<title><code>${(arg.argname + ' (out)') if arg.direction == 'inout' else arg.argname}</code></title> +${formatter.format(node, arg.doc)} +</item> +% endfor +</terms> +% endif +</%block> + diff --git a/giscanner/doctemplates/Gjs/class.tmpl b/giscanner/doctemplates/Gjs/class.tmpl index 887c646b..d8433704 100644 --- a/giscanner/doctemplates/Gjs/class.tmpl +++ b/giscanner/doctemplates/Gjs/class.tmpl @@ -3,16 +3,19 @@ <synopsis><code> const ${namespace.name} = imports.gi.${namespace.name}; -let ${formatter.to_underscores(node.name).lower()} = new ${namespace.name}.${node.name}(\ +let ${formatter.to_lower_camel_case(node.name)} = new ${namespace.name}.${node.name}(\ +% if isinstance(node, (ast.Class, ast.Interface)): % if len(node.properties) > 0: { % for ix, property_ in enumerate(node.properties): -% if property_.construct or property_.construct_only or property_.writable: +% if (property_.construct or property_.construct_only) and property_.writable: <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>: value, % endif % endfor }\ % endif +% else: +${formatter.format_gboxed_constructor(node)}\ +% endif ); - </code></synopsis> -</%block> + </code></synopsis></%block> diff --git a/giscanner/doctemplates/Gjs/field.tmpl b/giscanner/doctemplates/Gjs/field.tmpl new file mode 100644 index 00000000..dda82469 --- /dev/null +++ b/giscanner/doctemplates/Gjs/field.tmpl @@ -0,0 +1,9 @@ +<%inherit file="/base.tmpl"/> +<%block name="info"> + ${formatter.format_xref(node.parent, type="guide", group=page_kind)} + <title type="link" role="topic">${node.name}</title> +</%block> +<%block name="synopsis"> + <synopsis><code mime="text/x-gjs"> +${node.parent.name}.${formatter.to_underscores(node)}: ${formatter.format_type(node.type, True)} (${formatter.format_property_flags(node)}) + </code></synopsis></%block> diff --git a/giscanner/doctemplates/Gjs/function.tmpl b/giscanner/doctemplates/Gjs/function.tmpl index e0fd9612..012978ac 100644 --- a/giscanner/doctemplates/Gjs/function.tmpl +++ b/giscanner/doctemplates/Gjs/function.tmpl @@ -6,7 +6,7 @@ <api:type>${formatter.format_type(node.retval.type) | x}</api:type> </api:returns> <api:name>${node.symbol}</api:name> -% for arg in formatter.get_parameters(node): +% for arg in formatter.get_in_parameters(node): % if arg.type.ctype == '<varargs>': <api:varargs/> % else: @@ -19,30 +19,29 @@ </api:function> </%block> <%block name="synopsis"> -<synopsis><code mime="text/x-gjs"> + <synopsis><code mime="text/x-gjs"> function \ ${node.name}(\ -${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in formatter.get_parameters(node))}\ -):${formatter.format_type(node.retval.type)} { +${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\ +): ${formatter.format_out_parameters(node)} { // Gjs wrapper for ${node.symbol}() } -</code></synopsis> -</%block> + </code></synopsis></%block> <%block name="details"> -% if formatter.get_parameters(node) or node.retval: +% if formatter.has_any_parameters(node): <terms> -% for arg in formatter.get_parameters(node): +% for arg in formatter.get_in_parameters(node): <item> <title><code>${arg.argname}</code></title> ${formatter.format(node, arg.doc)} </item> % endfor -% if node.retval and node.retval.type.ctype != 'void': +% for arg in formatter.get_out_parameters(node): <item> -<title><code>Returns</code></title> -${formatter.format(node, node.retval.doc)} +<title><code>${(arg.argname + ' (out)') if arg.direction == 'inout' else arg.argname}</code></title> +${formatter.format(node, arg.doc)} </item> -% endif +% endfor </terms> % endif </%block> diff --git a/giscanner/doctemplates/Gjs/interface.tmpl b/giscanner/doctemplates/Gjs/interface.tmpl new file mode 100644 index 00000000..2f01f20f --- /dev/null +++ b/giscanner/doctemplates/Gjs/interface.tmpl @@ -0,0 +1,17 @@ +<%inherit file="/class.tmpl"/> +<%block name="synopsis"> + <synopsis><code> +const ${namespace.name} = imports.gi.${namespace.name}; + +let ${formatter.to_underscores(node).lower()} = new ${namespace.name}.${node.name}(\ +% if len(node.properties) > 0: +{ +% for ix, property_ in enumerate(node.properties): +% if (property_.construct or property_.construct_only) and property_.writable: + <link xref='${namespace.name}.${node.name}-${property_.name}'>${property_.name.replace('-', '_')}</link>: value, +% endif +% endfor +}\ +% endif +); + </code></synopsis></%block> diff --git a/giscanner/doctemplates/Gjs/property.tmpl b/giscanner/doctemplates/Gjs/property.tmpl index 3316a00c..dda82469 100644 --- a/giscanner/doctemplates/Gjs/property.tmpl +++ b/giscanner/doctemplates/Gjs/property.tmpl @@ -4,7 +4,6 @@ <title type="link" role="topic">${node.name}</title> </%block> <%block name="synopsis"> -<synopsis><code mime="text/x-python"> -"${node.name}" ${formatter.format_type(node.type)} : ${formatter.format_property_flags(node)} -</code></synopsis> -</%block> + <synopsis><code mime="text/x-gjs"> +${node.parent.name}.${formatter.to_underscores(node)}: ${formatter.format_type(node.type, True)} (${formatter.format_property_flags(node)}) + </code></synopsis></%block> diff --git a/giscanner/doctemplates/Gjs/signal.tmpl b/giscanner/doctemplates/Gjs/signal.tmpl index 084d9743..7c508162 100644 --- a/giscanner/doctemplates/Gjs/signal.tmpl +++ b/giscanner/doctemplates/Gjs/signal.tmpl @@ -4,21 +4,22 @@ <title type="link" role="topic">${node.name}</title> </%block> <%block name="synopsis"> -<synopsis><code mime="text/x-python"> -function callback(${formatter.to_underscores(node.parent.name).lower()}, \ -% for arg in formatter.get_parameters(node): -${arg.argname}:${formatter.format_type(arg.type)}, \ + <synopsis><code mime="text/x-gjs"> +connect('${node.name}', function (${formatter.to_lower_camel_case(node.parent.name)}, \ +% for arg in formatter.get_in_parameters(node): +% if arg.type.target_fundamental != 'none': +${arg.argname}: ${formatter.format_type(arg.type, True)}, \ +% endif % endfor -):${formatter.format_type(node.retval.type)}; -</code></synopsis> -</%block> +): ${formatter.format_type(node.retval.type, True)}); + </code></synopsis></%block> <%block name="details"> <terms> <item> -<title><code>${formatter.to_underscores(node.parent.name).lower()}</code></title> +<title><code>${formatter.to_lower_camel_case(node.parent.name)}</code></title> <p>instance of ${formatter.format_xref(node.parent)} that is emitting the signal</p> </item> -% for arg in formatter.get_parameters(node): +% for arg in formatter.get_in_parameters(node): <item> <title><code>${arg.argname}</code></title> ${formatter.format(node, arg.doc)} diff --git a/giscanner/doctemplates/Gjs/vfunc.tmpl b/giscanner/doctemplates/Gjs/vfunc.tmpl index 1cbe511c..2bd1127d 100644 --- a/giscanner/doctemplates/Gjs/vfunc.tmpl +++ b/giscanner/doctemplates/Gjs/vfunc.tmpl @@ -1,16 +1,15 @@ <%inherit file="/base.tmpl"/> <%block name="synopsis"> -<synopsis><code mime="text/x-gjs"> + <synopsis><code mime="text/x-gjs"> function vfunc_${node.name}(\ -${', '.join('%s:%s' % (arg.argname, formatter.format_type(arg.type)) for arg in formatter.get_parameters(node))}\ -):${formatter.format_type(node.retval.type)} { +${', '.join('%s: %s' % (arg.argname, formatter.format_type(arg.type, True)) for arg in formatter.get_in_parameters(node))}\ +): ${formatter.format_out_parameters(node)} { } -</code></synopsis> -</%block> + </code></synopsis></%block> <%block name="details"> -% if formatter.get_parameters(node) or node.retval: +% if formatter.get_in_parameters(node) or node.retval: <terms> -% for arg in formatter.get_parameters(node): +% for arg in formatter.get_in_parameters(node): <item> <title><code>${arg.argname}</code></title> ${formatter.format(node, arg.doc)} @@ -25,3 +24,4 @@ ${formatter.format(node, node.retval.doc)} </terms> % endif </%block> + |