From b8599bff9f0f45703373d7b52b0a25a4abd290f7 Mon Sep 17 00:00:00 2001 From: Daniel Kolesa Date: Tue, 9 Aug 2016 17:18:59 +0100 Subject: [PATCH] docs: add since tag writing into doctree --- src/scripts/elua/apps/docgen/doctree.lua | 28 ++++++++++++++++-- src/scripts/elua/apps/gendoc.lua | 37 +++++++----------------- 2 files changed, 36 insertions(+), 29 deletions(-) diff --git a/src/scripts/elua/apps/docgen/doctree.lua b/src/scripts/elua/apps/docgen/doctree.lua index a46c9b4817..df493588cc 100644 --- a/src/scripts/elua/apps/docgen/doctree.lua +++ b/src/scripts/elua/apps/docgen/doctree.lua @@ -19,6 +19,21 @@ local gen_doc_refd = function(str) return table.concat(pars, "\n\n") end +local add_since = function(str, since) + if not since then + return str + end + local buf = writer.Buffer() + if not str then + buf:write_i("Since " .. since) + return buf:finish() + end + buf:write_raw(str) + buf:write_nl(2) + buf:write_i("Since " .. since) + return buf:finish() +end + M.Doc = Node:clone { __ctor = function(self, doc) self.doc = doc @@ -56,7 +71,7 @@ M.Doc = Node:clone { return gen_doc_refd(doc1:summary_get()) end, - full_get = function(self, doc2) + full_get = function(self, doc2, write_since) if not self.doc and (not doc2 or not doc2.doc) then return "No description supplied." end @@ -67,6 +82,7 @@ M.Doc = Node:clone { local sum1 = doc1:summary_get() local desc1 = doc1:description_get() local edoc = "" + local since if doc2 then local sum2 = doc2:summary_get() local desc2 = doc2:description_get() @@ -75,11 +91,17 @@ M.Doc = Node:clone { else edoc = "\n\n" .. sum2 .. "\n\n" .. desc2 end + if write_since then + since = doc2:since_get() + end + end + if not since and write_since then + since = doc1:since_get() end if not desc1 then - return gen_doc_refd(sum1 .. edoc) + return add_since(gen_doc_refd(sum1 .. edoc), since) end - return gen_doc_refd(sum1 .. "\n\n" .. desc1 .. edoc) + return add_since(gen_doc_refd(sum1 .. "\n\n" .. desc1 .. edoc), since) end } diff --git a/src/scripts/elua/apps/gendoc.lua b/src/scripts/elua/apps/gendoc.lua index 5bc418f31d..1aab98a339 100644 --- a/src/scripts/elua/apps/gendoc.lua +++ b/src/scripts/elua/apps/gendoc.lua @@ -432,24 +432,9 @@ local build_ref = function() f:finish() end -local write_full_doc = function(f, doc1, doc2) - if not doc2 then - doc2 = dtree.Doc() - end - f:write_raw(doc1:full_get(doc2)) - local since = doc2:since_get() - if not since then - since = doc1:since_get() - end - if since then - f:write_nl(2) - f:write_i("Since " .. since) - end -end - local write_full_fdoc = function(f, fn, ftype) - write_full_doc(f, dtree.Doc(fn:documentation_get(eolian.function_type.METHOD)), - get_fallback_fdoc(fn, ftype)) + f:write_raw(dtree.Doc(fn:documentation_get(eolian.function_type.METHOD)) + :full_get(get_fallback_fdoc(fn, ftype), true)) end local build_inherits @@ -774,7 +759,7 @@ local build_class = function(cl) f:write_nl() f:write_h("Description", 3) - write_full_doc(f, dtree.Doc(cl:documentation_get())) + f:write_raw(dtree.Doc(cl:documentation_get()):full_get(nil, true)) f:write_nl(2) build_functable(f, "Methods", "Method name", cl, eolian.function_type.METHOD) @@ -831,7 +816,7 @@ local build_alias = function(tp) write_tsigs(f, tp) f:write_h("Description", 3) - write_full_doc(f, dtree.Doc(tp:documentation_get())) + f:write_raw(dtree.Doc(tp:documentation_get()):full_get(nil, true)) f:write_nl(2) f:finish() @@ -844,7 +829,7 @@ local build_struct = function(tp) write_tsigs(f, tp) f:write_h("Description", 3) - write_full_doc(f, dtree.Doc(tp:documentation_get())) + f:write_raw(dtree.Doc(tp:documentation_get()):full_get(nil, true)) f:write_nl(2) f:write_h("Fields", 3) @@ -869,7 +854,7 @@ local build_enum = function(tp) write_tsigs(f, tp) f:write_h("Description", 3) - write_full_doc(f, dtree.Doc(tp:documentation_get())) + f:write_raw(dtree.Doc(tp:documentation_get()):full_get(nil, true)) f:write_nl(2) f:write_h("Fields", 3) @@ -987,7 +972,7 @@ build_method = function(fn, cl) end f:write_h("Description", 3) - write_full_doc(f, dtree.Doc(fn:documentation_get(eolian.function_type.METHOD))) + f:write_raw(dtree.Doc(fn:documentation_get(eolian.function_type.METHOD)):full_get(nil, true)) f:write_nl() f:finish() @@ -1036,7 +1021,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, dtree.Doc(doc)) + f:write_raw(dtree.Doc(doc):full_get(nil, true)) end if (isget and gdoc) or (isset and sdoc) then f:write_nl(2) @@ -1049,7 +1034,7 @@ build_property = function(fn, cl) else f:write_h("Description", 3) end - write_full_doc(f, dtree.Doc(gdoc)) + f:write_raw(dtree.Doc(gdoc):full_get(nil, true)) if isset and sdoc then f:write_nl(2) end @@ -1061,7 +1046,7 @@ build_property = function(fn, cl) else f:write_h("Description", 3) end - write_full_doc(f, dtree.Doc(sdoc)) + f:write_raw(dtree.Doc(sdoc):full_get(nil, true)) end f:write_nl() @@ -1109,7 +1094,7 @@ build_event = function(ev, cl) f:write_nl() f:write_h("Description", 3) - write_full_doc(f, dtree.Doc(ev:documentation_get())) + f:write_raw(dtree.Doc(ev:documentation_get()):full_get(nil, true)) f:write_nl() f:finish()