From f2e5ba882e22f5fe7b1db408da7da419391d7965 Mon Sep 17 00:00:00 2001 From: Tomeu Vizoso Date: Fri, 12 Aug 2011 15:19:36 +0200 Subject: g-ir-doc-tool: Generate parameter list in the detail --- giscanner/docbookwriter.py | 54 +- tests/doctool/GIRepository-2.0-expected.xml | 785 ++++++++++++++++++++++++++++ 2 files changed, 824 insertions(+), 15 deletions(-) diff --git a/giscanner/docbookwriter.py b/giscanner/docbookwriter.py index 93c26d7c..222942fa 100644 --- a/giscanner/docbookwriter.py +++ b/giscanner/docbookwriter.py @@ -51,17 +51,15 @@ class DocBookFormatter(object): def render_parameter(self, param_type, param_name): return "%s %s" % (param_type, param_name) - def _render_parameter(self, param): - self._writer.push_tag("parameter", []) - - if param.type.ctype is not None: - link_dest = param.type.ctype.replace("*", "") - else: - link_dest = param.type.ctype - self._writer.push_tag("link", [("linkend", "%s" % link_dest)]) - - self._writer.write_tag("type", [], self.get_type_string(param.type)) - self._writer.pop_tag() + def _render_parameter(self, param, extra_content=''): + with self._writer.tagcontext("parameter"): + if param.type.ctype is not None: + link_dest = param.type.ctype.replace("*", "") + else: + link_dest = param.type.ctype + with self._writer.tagcontext("link", [("linkend", "%s" % link_dest)]): + self._writer.write_tag("type", [], self.get_type_string(param.type)) + self._writer.write_line(extra_content) def _render_parameters(self, parent, parameters): self._writer.write_line( @@ -80,14 +78,12 @@ class DocBookFormatter(object): else: first_param = False - self._render_parameter(param) if not param == params[-1]: comma = ", " else: comma = "" - - self._writer.write_line(" %s%s" % (param.argname, comma)) - self._writer.pop_tag() + extra_content = " %s%s" % (param.argname, comma) + self._render_parameter(param, extra_content) self._writer.write_line(");\n") @@ -151,6 +147,30 @@ class DocBookFormatter(object): self._render_parameters(method, method.parameters) self._writer.enable_whitespace() + def render_param_list(self, entity): + method = entity.get_ast() + + self._render_param(method.parent_class.name.lower(), 'instance') + for param in method.parameters: + self._render_param(param.argname, param.doc) + self._render_param('Returns', method.retval.doc) + + def _render_param(self, argname, doc): + with self._writer.tagcontext('varlistentry'): + with self._writer.tagcontext('term'): + self._writer.disable_whitespace() + try: + with self._writer.tagcontext('parameter'): + self._writer.write_line(argname) + if doc is not None: + self._writer.write_line(' :') + finally: + self._writer.enable_whitespace() + if doc is not None: + with self._writer.tagcontext('listitem'): + with self._writer.tagcontext('simpara'): + self._writer.write_line(doc) + def render_property(self, entity, link=False): prop = entity.get_ast() @@ -394,6 +414,10 @@ class DocBookWriter(object): self._formatter.render_method(entity) self._writer.write_tag("para", [], entity.get_ast().doc) + + with self._writer.tagcontext("variablelist", [("role", "params")]): + self._formatter.render_param_list(entity) + self._writer.pop_tag() def _render_property(self, entity): diff --git a/tests/doctool/GIRepository-2.0-expected.xml b/tests/doctool/GIRepository-2.0-expected.xml index 44265642..e6097ddb 100644 --- a/tests/doctool/GIRepository-2.0-expected.xml +++ b/tests/doctool/GIRepository-2.0-expected.xml @@ -55,6 +55,35 @@ Using pointer comparison is not practical since many functions return different instances of #GIBaseInfo that refers to the same part of the TypeLib; use this function instead to do #GIBaseInfo comparisons. + + + +baseinfo : + + + instance + + + + + +info2 : + + + a #GIBaseInfo + + + + + +Returns : + + + %TRUE if and only if @info1 equals @info2. + + + + g_base_info_get_attribute () @@ -66,6 +95,35 @@ TypeLib; use this function instead to do #GIBaseInfo comparisons. gchar* name); Retrieve an arbitrary attribute associated with this node. + + + +baseinfo : + + + instance + + + + + +name : + + + a freeform string naming an attribute + + + + + +Returns : + + + The value of the attribute, or %NULL if no such attribute exists + + + + g_base_info_get_container () @@ -78,6 +136,26 @@ TypeLib; use this function instead to do #GIBaseInfo comparisons. Obtain the container of the @info. The container is the parent GIBaseInfo. For instance, the parent of a #GIFunctionInfo is an #GIObjectInfo or #GIInterfaceInfo. + + + +baseinfo : + + + instance + + + + + +Returns : + + + the container + + + + g_base_info_get_name () @@ -90,6 +168,26 @@ GIBaseInfo. For instance, the parent of a #GIFunctionInfo is an Obtain the name of the @info. What the name represents depends on the #GIInfoType of the @info. For instance for #GIFunctionInfo it is the name of the function. + + + +baseinfo : + + + instance + + + + + +Returns : + + + the name of @info or %NULL if it lacks a name. + + + + g_base_info_get_namespace () @@ -100,6 +198,26 @@ the name of the function. gchar* g_base_info_get_namespace (GIBaseInfo* baseinfo); Obtain the namespace of @info. + + + +baseinfo : + + + instance + + + + + +Returns : + + + the namespace + + + + g_base_info_get_typelib () @@ -110,6 +228,26 @@ the name of the function. GITypelib* g_base_info_get_typelib (GIBaseInfo* baseinfo); Obtain the typelib this @info belongs to + + + +baseinfo : + + + instance + + + + + +Returns : + + + the typelib. + + + + g_base_info_is_deprecated () @@ -121,6 +259,26 @@ the name of the function. Obtain whether the @info is represents a metadata which is deprecated or not. + + + +baseinfo : + + + instance + + + + + +Returns : + + + %TRUE if deprecated + + + + g_base_info_iterate_attributes () @@ -153,6 +311,53 @@ while (g_base_info_iterate_attributes (info, &iter, &name, &value)) } </programlisting> </example> + + + +baseinfo : + + + instance + + + + + +iterator : + + + a #GIAttributeIter structure, must be initialized; see below + + + + + +name : + + + Returned name, must not be freed + + + + + +value : + + + Returned name, must not be freed + + + + + +Returns : + + + %TRUE if there are more attributes + + + + g_base_info_ref () @@ -163,6 +368,26 @@ while (g_base_info_iterate_attributes (info, &iter, &name, &value)) GIBaseInfo* g_base_info_ref (GIBaseInfo* baseinfo); Increases the reference count of @info. + + + +baseinfo : + + + instance + + + + + +Returns : + + + the same @info. + + + + g_base_info_unref () @@ -174,6 +399,21 @@ while (g_base_info_iterate_attributes (info, &iter, &name, &value)) Decreases the reference count of @info. When its reference count drops to 0, the info is freed. + + + +baseinfo : + + + instance + + + + + +Returns + + @@ -242,6 +482,35 @@ drops to 0, the info is freed. Obtain an unordered list of versions (either currently loaded or available) for @namespace_ in this @repository. + + + +repository : + + + instance + + + + + +namespace_ : + + + GI namespace, e.g. "Gtk" + + + + + +Returns : + + + the array of versions. + + + + g_irepository_find_by_gtype () @@ -258,6 +527,35 @@ the type must first have been loaded. There is currently no mechanism for determining the namespace which corresponds to an arbitrary GType - thus, this function will operate most reliably when you know the GType to originate from be from a loaded namespace. + + + +repository : + + + instance + + + + + +gtype : + + + GType to search for + + + + + +Returns : + + + #GIBaseInfo representing metadata about @type, or %NULL + + + + g_irepository_find_by_name () @@ -273,6 +571,44 @@ when you know the GType to originate from be from a loaded namespace. this function for a particular namespace, you must call #g_irepository_require once to load the namespace, or otherwise ensure the namespace has already been loaded. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace which will be searched + + + + + +name : + + + Entry name to find + + + + + +Returns : + + + #GIBaseInfo representing metadata about @name, or %NULL + + + + g_irepository_get_c_prefix () @@ -287,6 +623,35 @@ ensure the namespace has already been loaded. associated with the given introspection namespace. Each C symbol starts with this prefix, as well each #GType in the library. such as #g_irepository_require before calling this function. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace to inspect + + + + + +Returns : + + + C namespace prefix, or %NULL if none associated + + + + g_irepository_get_dependencies () @@ -300,6 +665,35 @@ such as #g_irepository_require before calling this function. Return an array of all (transitive) dependencies for namespace form <code>namespace-version</code>. such as #g_irepository_require before calling this function. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace of interest + + + + + +Returns : + + + Zero-terminated string array of versioned dependencies + + + + g_irepository_get_info () @@ -316,6 +710,44 @@ given namespace @namespace_. The namespace must have already been loaded before calling this function. See g_irepository_get_n_infos() to find the maximum number of entries. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace to inspect + + + + + +index : + + + 0-based offset into namespace metadata for entry + + + + + +Returns : + + + #GIBaseInfo containing metadata + + + + g_irepository_get_loaded_namespaces () @@ -326,6 +758,26 @@ entries. gchar** g_irepository_get_loaded_namespaces (GIRepository* repository); Return the list of currently loaded namespaces. + + + +repository : + + + instance + + + + + +Returns : + + + List of namespaces + + + + g_irepository_get_n_infos () @@ -339,6 +791,35 @@ entries. This function returns the number of metadata entries in given namespace @namespace_. The namespace must have already been loaded before calling this function. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace to inspect + + + + + +Returns : + + + number of metadata entries + + + + g_irepository_get_shared_library () @@ -354,6 +835,35 @@ associated with the given namespace @namespace_. There may be no shared library path associated, in which case this function will return %NULL. such as #g_irepository_require before calling this function. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace to inspect + + + + + +Returns : + + + Full path to shared library, or %NULL if none associated + + + + g_irepository_get_typelib_path () @@ -368,6 +878,35 @@ such as #g_irepository_require before calling this function. .typelib file it was loaded from. If the typelib for namespace @namespace_ was included in a shared library, return the special string "$lt;builtin$gt;". + + + +repository : + + + instance + + + + + +namespace_ : + + + GI namespace to use, e.g. "Gtk" + + + + + +Returns : + + + Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded + + + + g_irepository_get_version () @@ -381,6 +920,35 @@ the special string "$lt;builtin$gt;". This function returns the loaded version associated with the given namespace @namespace_. such as #g_irepository_require before calling this function. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace to inspect + + + + + +Returns : + + + Loaded version + + + + g_irepository_is_registered () @@ -398,6 +966,44 @@ only be useful in unusual circumstances; in order to act upon metadata in the namespace, you should call #g_irepository_require instead which will ensure the namespace is loaded, and return as quickly as this function will if it has already been loaded. + + + +repository : + + + instance + + + + + +namespace_ : + + + Namespace of interest + + + + + +version : + + + Required version, may be %NULL for latest + + + + + +Returns : + + + %TRUE if namespace-version is loaded, %FALSE otherwise + + + + g_irepository_load_typelib () @@ -410,6 +1016,29 @@ quickly as this function will if it has already been loaded. GIRepositoryLoadFlags flags); + + + +repository : + + + instance + + + + + +typelib + + + +flags + + + +Returns + + g_irepository_require () @@ -427,6 +1056,53 @@ If @namespace_ is not loaded, this function will search for a ".typelib" file using the repository search path. In addition, a version @version of namespace may be specified. If @version is not specified, the latest will be used. + + + +repository : + + + instance + + + + + +namespace_ : + + + GI namespace to use, e.g. "Gtk" + + + + + +version : + + + Version of namespace, may be %NULL for latest + + + + + +flags : + + + Set of %GIRepositoryLoadFlags, may be 0 + + + + + +Returns : + + + a pointer to the #GITypelib if successful, %NULL otherwise + + + + g_irepository_require_private () @@ -445,6 +1121,62 @@ If @namespace_ is not loaded, this function will search for a ".typelib" file within the private directory only. In addition, a version @version of namespace should be specified. If @version is not specified, the latest will be used. + + + +repository : + + + instance + + + + + +typelib_dir : + + + Private directory where to find the requested typelib + + + + + +namespace_ : + + + GI namespace to use, e.g. "Gtk" + + + + + +version : + + + Version of namespace, may be %NULL for latest + + + + + +flags : + + + Set of %GIRepositoryLoadFlags, may be 0 + + + + + +Returns : + + + a pointer to the #GITypelib if successful, %NULL otherwise + + + + @@ -490,6 +1222,21 @@ not specified, the latest will be used. void g_typelib_free (GITypelib* typelib); + + + +typelib : + + + instance + + + + + +Returns + + g_typelib_get_namespace () @@ -500,6 +1247,21 @@ not specified, the latest will be used. gchar* g_typelib_get_namespace (GITypelib* typelib); + + + +typelib : + + + instance + + + + + +Returns + + g_typelib_symbol () @@ -512,6 +1274,29 @@ not specified, the latest will be used. gpointer* symbol); + + + +typelib : + + + instance + + + + + +symbol_name + + + +symbol + + + +Returns + + -- cgit v1.2.1