summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Kolesa <d.kolesa@osg.samsung.com>2017-01-20 17:20:28 +0100
committerDaniel Kolesa <d.kolesa@osg.samsung.com>2017-01-20 17:20:28 +0100
commit3090e9c3ae3b12e36cf62dff224d6f6146bcc9d4 (patch)
treebbce2e6969a280465cf4df27de45f1c8fdb4df24
parentc2b6fbccbc5f2ab2defe72c9e11d6ac1daac083e (diff)
docs: WIP overridden method/property documentation support in docgen
-rw-r--r--src/scripts/elua/apps/docgen/doctree.lua14
-rw-r--r--src/scripts/elua/apps/docgen/writer.lua7
-rw-r--r--src/scripts/elua/apps/gendoc.lua167
3 files changed, 133 insertions, 55 deletions
diff --git a/src/scripts/elua/apps/docgen/doctree.lua b/src/scripts/elua/apps/docgen/doctree.lua
index 054000b6d9..f8876ced3b 100644
--- a/src/scripts/elua/apps/docgen/doctree.lua
+++ b/src/scripts/elua/apps/docgen/doctree.lua
@@ -230,7 +230,7 @@ M.Class = Node:clone {
230 implements_get = function(self) 230 implements_get = function(self)
231 local ret = {} 231 local ret = {}
232 for impl in self.class:implements_get() do 232 for impl in self.class:implements_get() do
233 ret[#ret + 1] = M.Implement(ret) 233 ret[#ret + 1] = M.Implement(impl)
234 end 234 end
235 return ret 235 return ret
236 end, 236 end,
@@ -1274,16 +1274,16 @@ M.Implement = Node:clone {
1274 return M.Function(func), tp 1274 return M.Function(func), tp
1275 end, 1275 end,
1276 1276
1277 doc_get = function(self, ftype) 1277 doc_get = function(self, ftype, inh)
1278 return M.Doc(self.impl:documentation_get(ftype)) 1278 return M.Doc(self.impl:documentation_get(ftype))
1279 end, 1279 end,
1280 1280
1281 fallback_doc_get = function(self) 1281 fallback_doc_get = function(self, inh)
1282 local ig, is = self:is_prop_get(), self:is_prop_set() 1282 local ig, is = self:is_prop_get(), self:is_prop_set()
1283 if ig and not is then 1283 if ig and not is then
1284 return self:doc_get(M.Function.PROP_GET) 1284 return self:doc_get(M.Function.PROP_GET, inh)
1285 elseif is and not ig then 1285 elseif is and not ig then
1286 return self:doc_get(M.Function.PROP_SET) 1286 return self:doc_get(M.Function.PROP_SET, inh)
1287 end 1287 end
1288 return nil 1288 return nil
1289 end, 1289 end,
@@ -1306,6 +1306,10 @@ M.Implement = Node:clone {
1306 1306
1307 is_prop_set = function(self) 1307 is_prop_set = function(self)
1308 return self.impl:is_prop_set() 1308 return self.impl:is_prop_set()
1309 end,
1310
1311 is_overridden = function(self, cl)
1312 return cl.class ~= self.impl:class_get()
1309 end 1313 end
1310} 1314}
1311 1315
diff --git a/src/scripts/elua/apps/docgen/writer.lua b/src/scripts/elua/apps/docgen/writer.lua
index 167d77fef0..fc3e423008 100644
--- a/src/scripts/elua/apps/docgen/writer.lua
+++ b/src/scripts/elua/apps/docgen/writer.lua
@@ -172,6 +172,13 @@ M.Writer = util.Object:clone {
172 ns[#ns] = nil 172 ns[#ns] = nil
173 end, 173 end,
174 174
175 write_inherited = function(self, ns)
176 ns[#ns + 1] = true
177 self:write_include(self.INCLUDE_PAGE, ns, {
178 editbutton = false, date = false, user = false, link = false
179 })
180 end,
181
175 write_fmt = function(self, fmt1, fmt2, ...) 182 write_fmt = function(self, fmt1, fmt2, ...)
176 self:write_raw(fmt1, ...) 183 self:write_raw(fmt1, ...)
177 self:write_raw(fmt2) 184 self:write_raw(fmt2)
diff --git a/src/scripts/elua/apps/gendoc.lua b/src/scripts/elua/apps/gendoc.lua
index 1d0ecac6fd..a1e5ac17a2 100644
--- a/src/scripts/elua/apps/gendoc.lua
+++ b/src/scripts/elua/apps/gendoc.lua
@@ -325,37 +325,6 @@ local build_reftable = function(f, title, ctitle, ctype, t, iscl)
325 f:write_nl() 325 f:write_nl()
326end 326end
327 327
328local build_functable = function(f, title, ctitle, cl, tp)
329 local t = cl:functions_get(tp)
330 if #t == 0 then
331 return
332 end
333 f:write_h(title, 2)
334 local nt = {}
335 for i, v in ipairs(t) do
336 local lbuf = writer.Buffer()
337 lbuf:write_link(v:nspaces_get(cl, true), v:name_get())
338 local pt = propt_to_type[v:type_get()]
339 if pt then
340 lbuf:write_raw(" ")
341 lbuf:write_i(pt)
342 end
343 local fimp = v:implement_get()
344 nt[#nt + 1] = {
345 lbuf:finish(),
346 fimp:doc_get(v.METHOD):brief_get(fimp:fallback_doc_get())
347 }
348 if v:type_str_get() == "property" then
349 build_property(v, cl)
350 else
351 build_method(v, cl)
352 end
353 end
354 table.sort(nt, function(v1, v2) return v1[1] < v2[1] end)
355 f:write_table({ ctitle, "Brief description" }, nt)
356 f:write_nl()
357end
358
359local build_ref = function() 328local build_ref = function()
360 local f = writer.Writer("reference", "EFL Reference") 329 local f = writer.Writer("reference", "EFL Reference")
361 330
@@ -693,6 +662,59 @@ local build_igraph = function(cl)
693 return graph 662 return graph
694end 663end
695 664
665local build_functable = function(f, title, ctitle, cl, tbl, over)
666 if #tbl == 0 then
667 return
668 end
669 f:write_h(title, 2)
670 local nt = {}
671 for i, impl in ipairs(tbl) do
672 local lbuf = writer.Buffer()
673 local func = impl:function_get()
674 lbuf:write_link(func:nspaces_get(cl, true), func:name_get())
675
676 local ft = dtree.Function.METHOD
677 if impl:is_prop_get() and impl:is_prop_set() then
678 ft = dtree.Function.PROPERTY
679 elseif impl:is_prop_get() then
680 ft = dtree.Function.PROP_GET
681 elseif impl:is_prop_set() then
682 ft = dtree.Function.PROP_SET
683 end
684
685 local pt = propt_to_type[ft]
686 if pt then
687 lbuf:write_raw(" ")
688 local llbuf = writer.Buffer()
689 llbuf:write_b(pt)
690 lbuf:write_i(llbuf:finish())
691 end
692
693 if over then
694 lbuf:write_raw(" ")
695 local llbuf = writer.Buffer()
696 local icl = impl:class_get()
697 llbuf:write_raw("[from ")
698 llbuf:write_link(icl:nspaces_get(true), icl:full_name_get())
699 llbuf:write_raw("]")
700 lbuf:write_i(llbuf:finish())
701 end
702
703 nt[#nt + 1] = {
704 lbuf:finish(),
705 impl:doc_get(func.METHOD, true):brief_get(impl:fallback_doc_get(true))
706 }
707 if impl:is_prop_get() or impl:is_prop_set() then
708 build_property(impl, cl)
709 else
710 build_method(impl, cl)
711 end
712 end
713 table.sort(nt, function(v1, v2) return v1[1] < v2[1] end)
714 f:write_table({ ctitle, "Brief description" }, nt)
715 f:write_nl()
716end
717
696local build_class = function(cl) 718local build_class = function(cl)
697 local cln = cl:nspaces_get() 719 local cln = cl:nspaces_get()
698 local f = writer.Writer(cln, cl:full_name_get()) 720 local f = writer.Writer(cln, cl:full_name_get())
@@ -718,9 +740,27 @@ local build_class = function(cl)
718 f:write_editable(cln, "description") 740 f:write_editable(cln, "description")
719 f:write_nl() 741 f:write_nl()
720 742
721 build_functable(f, "Methods", "Method name", cl, dtree.Function.METHOD) 743 local meths, props, methos, propos = {}, {}, {}, {}
722 build_functable(f, "Properties", "Property name", 744 for i, impl in ipairs(cl:implements_get()) do
723 cl, dtree.Function.PROPERTY) 745 if impl:is_prop_get() or impl:is_prop_set() then
746 if impl:is_overridden(cl) then
747 propos[#propos + 1] = impl
748 else
749 props[#props + 1] = impl
750 end
751 else
752 if impl:is_overridden(cl) then
753 methos[#methos + 1] = impl
754 else
755 meths[#meths + 1] = impl
756 end
757 end
758 end
759
760 build_functable(f, "Methods", "Method name", cl, meths, false)
761 build_functable(f, "Properties", "Property name", cl, props, false)
762 build_functable(f, "Overridden Methods", "Method name", cl, methos, true)
763 build_functable(f, "Overridden Properties", "Property name", cl, propos, true)
724 764
725 f:write_h("Events", 2) 765 f:write_h("Events", 2)
726 local evs = cl:events_get() 766 local evs = cl:events_get()
@@ -931,37 +971,64 @@ local build_vallist = function(f, pg, ps, title)
931 end 971 end
932end 972end
933 973
934build_method = function(fn, cl) 974local find_parent_impl
975find_parent_impl = function(fulln, cl)
976 for i, inh in ipairs(cl:inherits_get()) do
977 local pcl = dtree.Class.by_name_get(inh)
978 for j, impl in ipairs(pcl:implements_get()) do
979 if impl:full_name_get() == fulln then
980 return impl, pcl
981 end
982 end
983 local pimpl, pcl = find_parent_impl(fulln, pcl)
984 if pimpl then
985 return pimpl, pcl
986 end
987 end
988 -- unreachable with a validated database
989end
990
991build_method = function(impl, cl)
992 local over = impl:is_overridden(cl)
993 local fn = impl:function_get()
935 local mns = fn:nspaces_get(cl) 994 local mns = fn:nspaces_get(cl)
936 local f = writer.Writer(mns, cl:full_name_get() .. "." .. fn:name_get()) 995 local f = writer.Writer(mns, cl:full_name_get() .. "." .. fn:name_get())
937 stats.check_method(fn, cl) 996 stats.check_method(fn, cl)
938 997
939 f:write_h("Signature", 2) 998 local doc = impl:doc_get(fn.METHOD)
940 f:write_code(gen_method_sig(fn, cl)) 999 if over and not doc:exists() then
941 f:write_nl() 1000 local pimpl, pcl = find_parent_impl(impl:full_name_get(), cl)
1001 f:write_inherited(fn:nspaces_get(pcl))
1002 f:write_nl()
1003 else
1004 f:write_h("Signature", 2)
1005 f:write_code(gen_method_sig(fn, cl))
1006 f:write_nl()
942 1007
943 f:write_h("C signature", 2) 1008 f:write_h("C signature", 2)
944 f:write_code(gen_func_csig(fn, mns), "c") 1009 f:write_code(gen_func_csig(fn, mns), "c")
945 f:write_nl() 1010 f:write_nl()
1011
1012 local pars = fn:parameters_get()
1013 if #pars > 0 then
1014 f:write_h("Parameters", 2)
1015 build_parlist(f, pars)
1016 f:write_nl()
1017 end
946 1018
947 local pars = fn:parameters_get() 1019 f:write_h("Description", 2)
948 if #pars > 0 then 1020 f:write_raw(impl:doc_get(fn.METHOD):full_get(nil, true))
949 f:write_h("Parameters", 2)
950 build_parlist(f, pars)
951 f:write_nl() 1021 f:write_nl()
952 end 1022 end
953 1023
954 f:write_h("Description", 2)
955 f:write_raw(fn:implement_get():doc_get(fn.METHOD):full_get(nil, true))
956 f:write_nl()
957
958 f:write_editable(mns, "description") 1024 f:write_editable(mns, "description")
959 f:write_nl() 1025 f:write_nl()
960 1026
961 f:finish() 1027 f:finish()
962end 1028end
963 1029
964build_property = function(fn, cl) 1030build_property = function(impl, cl)
1031 local fn = impl:function_get()
965 local pns = fn:nspaces_get(cl) 1032 local pns = fn:nspaces_get(cl)
966 local f = writer.Writer(pns, cl:full_name_get() .. "." .. fn:name_get()) 1033 local f = writer.Writer(pns, cl:full_name_get() .. "." .. fn:name_get())
967 1034