summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndy Williams <andy@andywilliams.me>2017-12-13 16:07:41 +0000
committerAndy Williams <andy@andywilliams.me>2017-12-13 18:10:57 +0000
commited307bda4062f84873005dcae5fbf4ddfaf93e5d (patch)
tree3fa471bc5611f0718d9eba9ac5889a33e8d6997d
parentf8889239b654011bc117d7294d58a6ec791a559f (diff)
docs: Move inherited items to tables
Lots of refactoring required to make sense of the generator
-rw-r--r--src/scripts/elua/apps/gendoc.lua361
1 files changed, 222 insertions, 139 deletions
diff --git a/src/scripts/elua/apps/gendoc.lua b/src/scripts/elua/apps/gendoc.lua
index b35a8ac01b..c0543bd8ef 100644
--- a/src/scripts/elua/apps/gendoc.lua
+++ b/src/scripts/elua/apps/gendoc.lua
@@ -645,7 +645,7 @@ find_parent_briefdoc = function(fulln, cl)
645 return pdoc:brief_get(pdocf) 645 return pdoc:brief_get(pdocf)
646end 646end
647 647
648local build_functable = function(f, tcl, tbl, newm) 648local build_functable = function(f, tcl, tbl)
649 if #tbl == 0 then 649 if #tbl == 0 then
650 return 650 return
651 end 651 end
@@ -699,7 +699,76 @@ local build_functable = function(f, tcl, tbl, newm)
699 return f1:name_get() < f2:name_get() 699 return f1:name_get() < f2:name_get()
700 end) 700 end)
701 701
702 local prevcl = tcl 702 return nt
703end
704
705local write_description = function(f, impl, func, cl)
706 local over = impl:is_overridden(cl)
707 local bdoc
708
709 local doc = impl:doc_get(func.METHOD, true)
710 local docf = impl:fallback_doc_get(true)
711 if over and (not doc:exists() and (not docf or not docf:exists())) then
712 bdoc = find_parent_briefdoc(impl:full_name_get(), cl)
713 else
714 bdoc = doc:brief_get(docf)
715 end
716 if bdoc ~= "No description supplied." then
717 f:write_raw(bdoc)
718 end
719end
720
721local write_function = function(f, func, cl)
722 local llbuf = writer.Buffer()
723 llbuf:write_link(func:nspaces_get(cl, true), func:name_get())
724 f:write_b(llbuf:finish())
725
726 local pt = propt_to_type[func:type_get()]
727 if pt then
728 f:write_raw(" ")
729 local llbuf = writer.Buffer()
730 llbuf:write_b(pt)
731 f:write_i(llbuf:finish())
732 end
733end
734
735local write_scope = function(f, func)
736 local ftt = {
737 [func.scope.PROTECTED] = "protected",
738 [func.scope.PRIVATE] = "private"
739 }
740 if func:type_get() == func.PROPERTY then
741 local ft1, ft2 = ftt[func:scope_get(func.PROP_GET)],
742 ftt[func:scope_get(func.PROP_SET)]
743 if ft1 and ft1 == ft2 then
744 f:write_raw(" ")
745 f:write_m(ft1)
746 elseif ft1 or ft2 then
747 local s = ""
748 if ft1 then
749 s = s .. ft1 .. " get" .. (ft2 and ", " or "")
750 end
751 if ft2 then
752 s = s .. ft2 .. " set"
753 end
754 f:write_raw(" ")
755 f:write_m(s)
756 end
757 else
758 local ft = ftt[func:scope_get(func:type_get())]
759 if ft then
760 f:write_raw(" ")
761 f:write_m(ft)
762 end
763 end
764end
765
766local write_functable = function(f, tcl, tbl)
767 if #tbl == 0 then
768 return
769 end
770 local nt = build_functable(t, tcl, tbl)
771
703 local wrote = false 772 local wrote = false
704 for i, wt in ipairs(nt) do 773 for i, wt in ipairs(nt) do
705 local cl = wt[0] 774 local cl = wt[0]
@@ -710,64 +779,13 @@ local build_functable = function(f, tcl, tbl, newm)
710 local func = impl:function_get() 779 local func = impl:function_get()
711 local over = impl:is_overridden(cl) 780 local over = impl:is_overridden(cl)
712 781
713 -- class grouping for inheritance 782 -- function
714 if cl ~= prevcl then 783 write_function(f, func, cl)
715 if wrote then
716 f:write_br(true)
717 end
718
719 prevcl = cl
720 f:write_link(cl:nspaces_get(true), cl:full_name_get())
721 f:write_br(true)
722 f:write_raw("> ")
723 wrote = true
724 elseif not newm then
725 f:write_raw(", ")
726 end
727
728
729 local llbuf = writer.Buffer()
730 llbuf:write_link(func:nspaces_get(cl, true), func:name_get())
731 f:write_b(llbuf:finish())
732
733 local pt = propt_to_type[func:type_get()]
734 if pt then
735 f:write_raw(" ")
736 local llbuf = writer.Buffer()
737 llbuf:write_b(pt)
738 f:write_i(llbuf:finish())
739 end
740 -- scope 784 -- scope
741 local ftt = { 785 write_scope(f, func)
742 [func.scope.PROTECTED] = "protected", 786
743 [func.scope.PRIVATE] = "private" 787 -- overrides
744 } 788 if over then
745 if func:type_get() == func.PROPERTY then
746 local ft1, ft2 = ftt[func:scope_get(func.PROP_GET)],
747 ftt[func:scope_get(func.PROP_SET)]
748 if ft1 and ft1 == ft2 then
749 f:write_raw(" ")
750 f:write_m(ft1)
751 elseif ft1 or ft2 then
752 local s = ""
753 if ft1 then
754 s = s .. ft1 .. " get" .. (ft2 and ", " or "")
755 end
756 if ft2 then
757 s = s .. ft2 .. " set"
758 end
759 f:write_raw(" ")
760 f:write_m(s)
761 end
762 else
763 local ft = ftt[func:scope_get(func:type_get())]
764 if ft then
765 f:write_raw(" ")
766 f:write_m(ft)
767 end
768 end
769
770 if over and newm then
771 -- TODO: possibly also mention which part of a property was 789 -- TODO: possibly also mention which part of a property was
772 -- overridden and where, get/set override point might differ! 790 -- overridden and where, get/set override point might differ!
773 -- but we get latest doc every time so it's ok for now 791 -- but we get latest doc every time so it's ok for now
@@ -778,32 +796,22 @@ local build_functable = function(f, tcl, tbl, newm)
778 f:write_i(llbuf:finish()) 796 f:write_i(llbuf:finish())
779 end 797 end
780 798
781 if newm then 799 -- description
782 local doc = impl:doc_get(func.METHOD, true) 800 f:write_br(true)
783 local docf = impl:fallback_doc_get(true) 801 f:write_raw("> ")
784 local bdoc 802 write_description(f, impl, func, cl)
785 if over and (not doc:exists() and (not docf or not docf:exists())) then
786 bdoc = find_parent_briefdoc(impl:full_name_get(), cl)
787 else
788 bdoc = doc:brief_get(docf)
789 end
790 if bdoc ~= "No description supplied." then
791 f:write_br(true)
792 f:write_raw("> ")
793 f:write_raw(bdoc)
794 end
795 803
796 f:write_nl() 804 -- code snippets
797 local codes = {} 805 f:write_nl()
798 if func:type_get() ~= dtree.Function.PROPERTY then 806 local codes = {}
799 codes[#codes + 1] = gen_func_csig(func, func:type_get()) 807 if func:type_get() ~= dtree.Function.PROPERTY then
800 else 808 codes[#codes + 1] = gen_func_csig(func, func:type_get())
801 codes[#codes + 1] = gen_func_csig(func, dtree.Function.PROP_GET) 809 else
802 codes[#codes + 1] = gen_func_csig(func, dtree.Function.PROP_SET) 810 codes[#codes + 1] = gen_func_csig(func, dtree.Function.PROP_GET)
803 end 811 codes[#codes + 1] = gen_func_csig(func, dtree.Function.PROP_SET)
804 f:write_code(table.concat(codes, "\n"), "c")
805 f:write_br(true)
806 end 812 end
813 f:write_code(table.concat(codes, "\n"), "c")
814 f:write_br(true)
807 815
808 if cl == tcl then 816 if cl == tcl then
809 if impl:is_prop_get() or impl:is_prop_set() then 817 if impl:is_prop_get() or impl:is_prop_set() then
@@ -816,6 +824,45 @@ local build_functable = function(f, tcl, tbl, newm)
816 f:write_nl() 824 f:write_nl()
817end 825end
818 826
827local write_inherit_functable = function(f, tcl, tbl)
828 if #tbl == 0 then
829 return
830 end
831 local nt = build_functable(t, tcl, tbl)
832
833 local prevcl = tcl
834 for i, wt in ipairs(nt) do
835 local cl = wt[0]
836 local func = wt[1]
837 local impl = wt[2]
838
839 local ocl = impl:class_get()
840 local func = impl:function_get()
841
842 -- class grouping for inheritance
843 if cl ~= prevcl then
844 prevcl = cl
845 f:write_raw("^ ")
846 f:write_link(cl:nspaces_get(true), cl:full_name_get())
847 f:write_raw(" ^^^")
848 f:write_nl()
849 end
850
851 -- scope
852 f:write_raw("| ")
853 write_scope(f, func)
854 f:write_raw(" | ")
855 -- function
856 write_function(f, func, cl)
857 f:write_raw(" | ")
858 -- description
859 write_description(f, impl, func, cl)
860 f:write_raw(" |")
861 f:write_nl()
862 end
863 f:write_nl()
864end
865
819-- finds all stuff that is callable on a class, respecting 866-- finds all stuff that is callable on a class, respecting
820-- overrides and not duplicating, does a depth-first search 867-- overrides and not duplicating, does a depth-first search
821local find_callables 868local find_callables
@@ -830,7 +877,11 @@ find_callables = function(cl, omeths, events, written)
830 end 877 end
831 end 878 end
832 for i, ev in ipairs(pcl:events_get()) do 879 for i, ev in ipairs(pcl:events_get()) do
833 events[#events + 1] = { pcl, ev } 880 local evid = ev:name_get()
881 if not written[evid] then
882 events[#events + 1] = { pcl, ev }
883 written[evid] = true
884 end
834 end 885 end
835 find_callables(pcl, omeths, events, written) 886 find_callables(pcl, omeths, events, written)
836 end 887 end
@@ -867,75 +918,107 @@ local build_evtable = function(f, tcl, tbl, newm)
867 cl, ev = tcl, evt 918 cl, ev = tcl, evt
868 end 919 end
869 920
870 local llbuf = writer.Buffer()
871 llbuf:write_link(ev:nspaces_get(cl, true), ev:name_get())
872 lbuf:write_b(llbuf:finish())
873
874 local wt = {} 921 local wt = {}
875 wt[0] = cl 922 wt[0] = cl
876 wt[1] = ev 923 wt[1] = ev
877 -- name info 924 wt[2] = ev:name_get()
878 wt[2] = lbuf:finish() 925
879 926 nt[#nt + 1] = wt
880 if newm then 927 end
881 local bdoc = ev:doc_get():brief_get()
882 if bdoc ~= "No description supplied." then
883 lbuf:write_br(true)
884 lbuf:write_raw("> ")
885 lbuf:write_raw(bdoc)
886 end
887 928
888 lbuf:write_nl() 929 table.sort(nt, function(v1, v2)
889 lbuf:write_code(build_evcsig(ev), "c"); 930 if v1[0] ~= v2[0] then
890 lbuf:write_br() 931 return v1[0]:full_name_get() < v2[0]:full_name_get()
891 end 932 end
933
934 return v1[2] < v2[2]
935 end)
936
937 return nt
938end
939
940local write_event_scope = function(f, ev)
941 local ett = {
942 [ev.scope.PROTECTED] = "protected",
943 [ev.scope.PRIVATE] = "private"
944 }
945 local ets = ett[ev:scope_get()]
946 if ets then
947 f:write_raw(" ")
948 f:write_m(ets)
949 end
950end
951
952local write_evtable = function(f, tcl, tbl)
953 if #tbl == 0 then
954 return
955 end
956 local nt = build_evtable(f, tcl, tbl, true)
957 for i, wt in ipairs(nt) do
958 local evn
959 local cl, ev = wt[0], wt[1]
960
961 local llbuf = writer.Buffer()
962 llbuf:write_link(ev:nspaces_get(cl, true), wt[2])
963 f:write_b(llbuf:finish())
964
965 -- scope
966 write_event_scope(f, ev)
967
892 -- description 968 -- description
893 wt[#wt + 1] = lbuf:finish() 969 local bdoc = ev:doc_get():brief_get()
894 nt[#nt + 1] = wt 970 if bdoc ~= "No description supplied." then
971 f:write_br(true)
972 f:write_raw("> ")
973 f:write_raw(bdoc)
974 end
975
976 f:write_nl()
977 f:write_code(build_evcsig(ev), "c");
978 f:write_br()
895 979
896 if cl == tcl then 980 if cl == tcl then
897 build_event(ev, cl) 981 build_event(ev, cl)
898 end 982 end
899 end 983 end
900 table.sort(nt, function(v1, v2) return v1[2] < v2[2] end) 984end
901 for i = #nt, 1, -1 do 985
902 if i ~= 1 and nt[i][2] == nt[i - 1][2] then 986
903 table.remove(nt, i) 987local write_inherit_evtable = function(f, tcl, tbl)
904 end 988 if #tbl == 0 then
989 return
905 end 990 end
906 local prevcl = tcl 991 local nt = build_evtable(f, tcl, tbl, false)
907 local wrote = false 992 local prevcl
908 for i, item in ipairs(nt) do 993 for i, wt in ipairs(nt) do
909 local cl = item[0] 994 local evn
910 if cl ~= prevcl then 995 local cl, ev = wt[0], wt[1]
911 if wrote then
912 f:write_br(true)
913 end
914 996
997 if cl ~= prevcl then
915 prevcl = cl 998 prevcl = cl
999 f:write_raw("^ ")
916 f:write_link(cl:nspaces_get(true), cl:full_name_get()) 1000 f:write_link(cl:nspaces_get(true), cl:full_name_get())
917 f:write_br(true) 1001 f:write_raw(" ^^^")
918 f:write_raw("> ") 1002 f:write_nl()
919 wrote = true
920 elseif not newm then
921 f:write_raw(", ")
922 end 1003 end
923 1004
924 -- name 1005 f:write_raw("| ")
925 f:write_raw(item[2])
926 -- scope 1006 -- scope
927 local ev = item[1] 1007 write_event_scope(f, ev)
928 local ett = { 1008 f:write_raw(" | ")
929 [ev.scope.PROTECTED] = "protected", 1009
930 [ev.scope.PRIVATE] = "private" 1010 local llbuf = writer.Buffer()
931 } 1011 llbuf:write_link(ev:nspaces_get(cl, true), wt[2])
932 local ets = ett[ev:scope_get()] 1012 f:write_b(llbuf:finish())
933 if ets then 1013
934 f:write_raw(" ") 1014 f:write_raw(" | ")
935 f:write_m(ets) 1015 local bdoc = ev:doc_get():brief_get()
1016 if bdoc ~= "No description supplied." then
1017 f:write_raw(bdoc)
936 end 1018 end
937 -- desc 1019
938 f:write_raw(item[3]) 1020 f:write_raw(" |")
1021 f:write_nl()
939 end 1022 end
940end 1023end
941 1024
@@ -978,18 +1061,18 @@ local build_class = function(cl)
978 find_callables(cl, omeths, ievs, written) 1061 find_callables(cl, omeths, ievs, written)
979 1062
980 f:write_h("Members", 2) 1063 f:write_h("Members", 2)
981 build_functable(f, cl, meths, true) 1064 write_functable(f, cl, meths, true)
982 if #omeths ~= 0 then 1065 if #omeths ~= 0 then
983 f:write_h("Inherited", 3) 1066 f:write_h("Inherited", 3)
984 end 1067 end
985 build_functable(f, cl, omeths, false) 1068 write_inherit_functable(f, cl, omeths, false)
986 1069
987 f:write_h("Events", 2) 1070 f:write_h("Events", 2)
988 build_evtable(f, cl, cl:events_get(), true) 1071 write_evtable(f, cl, cl:events_get(), true)
989 if #ievs ~= 0 then 1072 if #ievs ~= 0 then
990 f:write_h("Inherited", 3) 1073 f:write_h("Inherited", 3)
991 end 1074 end
992 build_evtable(f, cl, ievs, false) 1075 write_inherit_evtable(f, cl, ievs, false)
993 1076
994 f:finish() 1077 f:finish()
995end 1078end