From: Daniel Kolesa Date: Tue, 9 Aug 2016 14:19:39 +0000 (+0100) Subject: docs: initial documentation tree X-Git-Tag: upstream/1.20.0~4860 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a31c9367be2abf076e55db3559711842af6439fa;p=platform%2Fupstream%2Fefl.git docs: initial documentation tree This will abstract away Eolian APIs to get more maintaineable code. For now, the Eolian_Documentation structure is abstracted away. --- diff --git a/src/Makefile_Elua.am b/src/Makefile_Elua.am index 96a6bf5..798f843 100644 --- a/src/Makefile_Elua.am +++ b/src/Makefile_Elua.am @@ -66,6 +66,7 @@ EXTRA_DIST2 += $(eluaapps_DATA) eluadocgendir = $(datadir)/elua/apps/docgen eluadocgen_DATA = \ + scripts/elua/apps/docgen/doctree.lua \ scripts/elua/apps/docgen/keyref.lua \ scripts/elua/apps/docgen/mappings.lua \ scripts/elua/apps/docgen/serializers.lua \ diff --git a/src/scripts/elua/apps/docgen/doctree.lua b/src/scripts/elua/apps/docgen/doctree.lua new file mode 100644 index 0000000..a46c9b4 --- /dev/null +++ b/src/scripts/elua/apps/docgen/doctree.lua @@ -0,0 +1,86 @@ +local util = require("util") + +local dutil = require("docgen.util") +local writer = require("docgen.writer") + +local M = {} + +local Node = util.Object:clone { +} + +local gen_doc_refd = function(str) + if not str then + return nil + end + local pars = dutil.str_split(str, "\n\n") + for i = 1, #pars do + pars[i] = writer.Buffer():write_par(pars[i]):finish() + end + return table.concat(pars, "\n\n") +end + +M.Doc = Node:clone { + __ctor = function(self, doc) + self.doc = doc + end, + + summary_get = function(self) + if not self.doc then + return nil + end + return self.doc:summary_get() + end, + + description_get = function(self) + if not self.doc then + return nil + end + return self.doc:description_get() + end, + + since_get = function(self) + if not self.doc then + return nil + end + return self.doc:since_get() + end, + + brief_get = function(self, doc2) + if not self.doc and (not doc2 or not doc2.doc) then + return "No description supplied." + end + local doc1, doc2 = self.doc, doc2 and doc2.doc or nil + if not doc1 then + doc1, doc2 = doc2, doc1 + end + return gen_doc_refd(doc1:summary_get()) + end, + + full_get = function(self, doc2) + if not self.doc and (not doc2 or not doc2.doc) then + return "No description supplied." + end + local doc1, doc2 = self.doc, doc2 and doc2.doc or nil + if not doc1 then + doc1, doc2 = doc2, doc1 + end + local sum1 = doc1:summary_get() + local desc1 = doc1:description_get() + local edoc = "" + if doc2 then + local sum2 = doc2:summary_get() + local desc2 = doc2:description_get() + if not desc2 then + if sum2 then edoc = "\n\n" .. sum2 end + else + edoc = "\n\n" .. sum2 .. "\n\n" .. desc2 + end + end + if not desc1 then + return gen_doc_refd(sum1 .. edoc) + end + return gen_doc_refd(sum1 .. "\n\n" .. desc1 .. edoc) + end +} + +return M diff --git a/src/scripts/elua/apps/gendoc.lua b/src/scripts/elua/apps/gendoc.lua index dce1257..5bc418f 100644 --- a/src/scripts/elua/apps/gendoc.lua +++ b/src/scripts/elua/apps/gendoc.lua @@ -9,22 +9,12 @@ local dutil = require("docgen.util") local writer = require("docgen.writer") local keyref = require("docgen.keyref") local ser = require("docgen.serializers") +local dtree = require("docgen.doctree") local use_dot, use_folded -- eolian to various doc elements conversions -local gen_doc_refd = function(str) - if not str then - return nil - end - local pars = dutil.str_split(str, "\n\n") - for i = 1, #pars do - pars[i] = writer.Buffer():write_par(pars[i]):finish() - end - return table.concat(pars, "\n\n") -end - local get_fallback_fdoc = function(f, ftype) if not ftype then local ft = f:type_get() @@ -34,54 +24,19 @@ local get_fallback_fdoc = function(f, ftype) end end if ftype then - return f:documentation_get(ftype) + return dtree.Doc(f:documentation_get(ftype)) end return nil end -local get_brief_doc = function(doc1, doc2) - if not doc1 and not doc2 then - return "No description supplied." - end - if not doc1 then - doc1, doc2 = doc2, doc1 - end - return gen_doc_refd(doc1:summary_get()) -end - local get_brief_fdoc = function(f, ftype) - return get_brief_doc(f:documentation_get(eolian.function_type.METHOD), - get_fallback_fdoc(f, ftype)) -end - -local get_full_doc = function(doc1, doc2) - if not doc1 and not doc2 then - return "No description supplied." - end - if not doc1 then - doc1, doc2 = doc2, doc1 - end - local sum1 = doc1:summary_get() - local desc1 = doc1:description_get() - local edoc = "" - if doc2 then - local sum2 = doc2:summary_get() - local desc2 = doc2:description_get() - if not desc2 then - if sum2 then edoc = "\n\n" .. sum2 end - else - edoc = "\n\n" .. sum2 .. "\n\n" .. desc2 - end - end - if not desc1 then - return gen_doc_refd(sum1 .. edoc) - end - return gen_doc_refd(sum1 .. "\n\n" .. desc1 .. edoc) + return dtree.Doc(f:documentation_get(eolian.function_type.METHOD)) + :brief_get(get_fallback_fdoc(f, ftype)) end local get_full_fdoc = function(f, ftype) - return get_full_doc(f:documentation_get(eolian.function_type.METHOD), - get_fallback_fdoc(f, ftype)) + return dtree.Doc(f:documentation_get(eolian.function_type.METHOD)) + :full_get(get_fallback_fdoc(f, ftype)) end local propt_to_type = { @@ -395,7 +350,7 @@ local build_reftable = function(f, title, ctitle, ctype, t) nt[#nt + 1] = { writer.Buffer():write_link(eomap.gen_nsp_eo(v, ctype, true), v:full_name_get()):finish(), - get_brief_doc(v:documentation_get()) + dtree.Doc(v:documentation_get()):brief_get() } end table.sort(nt, function(v1, v2) return v1[1] < v2[1] end) @@ -478,12 +433,12 @@ local build_ref = function() end local write_full_doc = function(f, doc1, doc2) - f:write_raw(get_full_doc(doc1, doc2)) - local since - if doc2 then - since = doc2:since_get() + if not doc2 then + doc2 = dtree.Doc() end - if not since and doc1 then + f:write_raw(doc1:full_get(doc2)) + local since = doc2:since_get() + if not since then since = doc1:since_get() end if since then @@ -493,7 +448,7 @@ local write_full_doc = function(f, doc1, doc2) end local write_full_fdoc = function(f, fn, ftype) - write_full_doc(f, fn:documentation_get(eolian.function_type.METHOD), + write_full_doc(f, dtree.Doc(fn:documentation_get(eolian.function_type.METHOD)), get_fallback_fdoc(fn, ftype)) end @@ -819,7 +774,7 @@ local build_class = function(cl) f:write_nl() f:write_h("Description", 3) - write_full_doc(f, cl:documentation_get()) + write_full_doc(f, dtree.Doc(cl:documentation_get())) f:write_nl(2) build_functable(f, "Methods", "Method name", cl, eolian.function_type.METHOD) @@ -836,7 +791,7 @@ local build_class = function(cl) local lbuf = writer.Buffer() lbuf:write_link(eomap.gen_nsp_ev(ev, cl, true), ev:name_get()) nt[#nt + 1] = { - lbuf:finish(), get_brief_doc(ev:documentation_get()) + lbuf:finish(), dtree.Doc(ev:documentation_get()):brief_get() } build_event(ev, cl) end @@ -876,7 +831,7 @@ local build_alias = function(tp) write_tsigs(f, tp) f:write_h("Description", 3) - write_full_doc(f, tp:documentation_get()) + write_full_doc(f, dtree.Doc(tp:documentation_get())) f:write_nl(2) f:finish() @@ -889,7 +844,7 @@ local build_struct = function(tp) write_tsigs(f, tp) f:write_h("Description", 3) - write_full_doc(f, tp:documentation_get()) + write_full_doc(f, dtree.Doc(tp:documentation_get())) f:write_nl(2) f:write_h("Fields", 3) @@ -898,7 +853,7 @@ local build_struct = function(tp) for fl in tp:struct_fields_get() do local buf = writer.Buffer() buf:write_b(fl:name_get()) - buf:write_raw(" - ", get_full_doc(fl:documentation_get())) + buf:write_raw(" - ", dtree.Doc(fl:documentation_get()):full_get()) arr[#arr + 1] = buf:finish() end f:write_list(arr) @@ -914,7 +869,7 @@ local build_enum = function(tp) write_tsigs(f, tp) f:write_h("Description", 3) - write_full_doc(f, tp:documentation_get()) + write_full_doc(f, dtree.Doc(tp:documentation_get())) f:write_nl(2) f:write_h("Fields", 3) @@ -923,7 +878,7 @@ local build_enum = function(tp) for fl in tp:enum_fields_get() do local buf = writer.Buffer() buf:write_b(fl:name_get()) - buf:write_raw(" - ", get_full_doc(fl:documentation_get())) + buf:write_raw(" - ", dtree.Doc(fl:documentation_get()):full_get()) arr[#arr + 1] = buf:finish() end f:write_list(arr) @@ -976,7 +931,7 @@ local build_parlist = function(f, pl, nodir) buf:write_raw(" ") buf:write_i(eomap.pdir_to_str[p:direction_get()]) end - buf:write_raw(" - ", get_full_doc(p:documentation_get())) + buf:write_raw(" - ", dtree.Doc(p:documentation_get()):full_get()) params[#params + 1] = buf:finish() end f:write_list(params) @@ -1032,7 +987,7 @@ build_method = function(fn, cl) end f:write_h("Description", 3) - write_full_doc(f, fn:documentation_get(eolian.function_type.METHOD)) + write_full_doc(f, dtree.Doc(fn:documentation_get(eolian.function_type.METHOD))) f:write_nl() f:finish() @@ -1081,7 +1036,7 @@ build_property = function(fn, cl) if isget and isset then f:write_h("Description", 3) if doc or (not gdoc and not sdoc) then - write_full_doc(f, doc) + write_full_doc(f, dtree.Doc(doc)) end if (isget and gdoc) or (isset and sdoc) then f:write_nl(2) @@ -1094,7 +1049,7 @@ build_property = function(fn, cl) else f:write_h("Description", 3) end - write_full_doc(f, gdoc) + write_full_doc(f, dtree.Doc(gdoc)) if isset and sdoc then f:write_nl(2) end @@ -1106,7 +1061,7 @@ build_property = function(fn, cl) else f:write_h("Description", 3) end - write_full_doc(f, sdoc) + write_full_doc(f, dtree.Doc(sdoc)) end f:write_nl() @@ -1154,7 +1109,7 @@ build_event = function(ev, cl) f:write_nl() f:write_h("Description", 3) - write_full_doc(f, ev:documentation_get()) + write_full_doc(f, dtree.Doc(ev:documentation_get())) f:write_nl() f:finish()