Merge pull request #8167 from garazdawi/lukas/stdlib/update_warn_missing_spec_doc

Add warn_missing_spec_documented to ignore functions with -doc false.

Author: garazdawi

bootstrap/lib/compiler/ebin/beam_a.beam

@@ -216,7 +216,8 @@ RELSYSDIR = $(RELEASE_PATH)/emulator_test
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_MAKE_FLAGS += 
+ERL_MAKE_FLAGS +=
+ERL_COMPILE_FLAGS += +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$($(ERL_COMPILE_FLAGS)))
 
 # ----------------------------------------------------

bootstrap/lib/compiler/ebin/beam_asm.beam

@@ -46,7 +46,7 @@ RELEPMDDIR   = $(RELEASE_PATH)/epmd_test
 # FLAGS
 # ----------------------------------------------------
 
-ERL_COMPILE_FLAGS += $(EPMD_FLAGS)
+ERL_COMPILE_FLAGS += $(EPMD_FLAGS) +nowarn_missing_spec_documented
 
 # ----------------------------------------------------
 # Targets

bootstrap/lib/compiler/ebin/beam_block.beam

@@ -9988,13 +9988,16 @@ Failure: `badarg` if `List` is an empty list `[]`.
 tl(_List) ->
     erlang:nif_error(undefined).
 
+-spec trace_session_create(Opts :: [{tracer, pid() | port()} |
+                                    {tracer, module(), term()}]) -> trace_session().
 -doc #{ since => <<"OTP-27">>, group => trace }.
 trace_session_create(Opts) ->
     try erts_internal:trace_session_create(Opts) of
         Ref -> Ref
     catch error:R:Stk ->
             error_with_inherited_info(R, [Opts], Stk)
     end.
+-spec trace_session_destroy(trace_session()) -> ok.
 -doc #{ since => <<"OTP-27">>, group => trace }.
 trace_session_destroy(Ref) ->
     try erts_internal:trace_session_destroy(Ref) of

bootstrap/lib/compiler/ebin/beam_bounds.beam

@@ -58,7 +58,7 @@ RELSYSDIR = $(RELEASE_PATH)/system_test
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_COMPILE_FLAGS +=
+ERL_COMPILE_FLAGS += +nowarn_missing_spec_documented
 
 # ----------------------------------------------------
 # Targets

bootstrap/lib/compiler/ebin/beam_call_types.beam

@@ -138,7 +138,7 @@ RELSYSDIR = $(RELEASE_PATH)/asn1_test
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_COMPILE_FLAGS += +warnings_as_errors +nowarn_export_all
+ERL_COMPILE_FLAGS += +warnings_as_errors +nowarn_export_all +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$(ERL_COMPILE_FLAGS))
 EBIN = .
 

bootstrap/lib/compiler/ebin/beam_clean.beam

@@ -115,7 +115,8 @@ DTD_FILES = \
 # FLAGS
 # ----------------------------------------------------
 ERL_COMPILE_FLAGS += -pa ../ebin -I../include -I $(ERL_TOP)/lib/snmp/include/ \
-	-I../../xmerl/inc/ -I $(ERL_TOP)/lib/kernel/include -Werror
+	-I../../xmerl/inc/ -I $(ERL_TOP)/lib/kernel/include -Werror \
+         +nowarn_missing_spec_documented
 
 # ----------------------------------------------------
 # Targets

bootstrap/lib/compiler/ebin/beam_core_to_ssa.beam

@@ -98,7 +98,7 @@ RELSYSDIR = $(RELEASE_PATH)/common_test_test
 # ----------------------------------------------------
 
 ERL_MAKE_FLAGS +=
-ERL_COMPILE_FLAGS +=
+ERL_COMPILE_FLAGS += +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$(ERL_COMPILE_FLAGS))
 
 EBIN = .

bootstrap/lib/compiler/ebin/beam_dict.beam

@@ -58,7 +58,7 @@ TS_TARGETS = $(TS_MODULES:%=$(EBIN)/%.$(EMULATOR))
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_COMPILE_FLAGS += -I../include -Werror
+ERL_COMPILE_FLAGS += -I../include -Werror +nowarn_missing_spec_documented
 
 # ----------------------------------------------------
 # Targets

bootstrap/lib/compiler/ebin/beam_digraph.beam

@@ -36,8 +36,6 @@
 
 -include_lib("kernel/include/eep48.hrl").
 
--moduledoc false.
-
 -define(DEFAULT_MODULE_DOC_LOC, 1).
 -define(DEFAULT_FORMAT, <<"text/markdown">>).
 
@@ -313,18 +311,18 @@ preprocessing(AST, State) ->
                              Funs = [% Order matters
                                      fun has_docs/2,
                                      fun extract_deprecated/2,
-                                     fun extract_exported_types0/2, % done
-                                     fun extract_signature_from_spec0/2,%done
+                                     fun extract_exported_types0/2,
+                                     fun extract_signature_from_spec0/2,
                                      fun track_documentation/2,      %must be before upsert_documentation_from_terminal_item/2
                                      fun upsert_documentation_from_terminal_item/2,
-                                     fun extract_docformat0/2, %done
-                                     fun extract_moduledoc0/2, %done
-                                     fun extract_module_meta/2, %done
-                                     fun extract_exported_funs/2, %done
-                                     fun extract_file/2, %done
+                                     fun extract_docformat0/2,
+                                     fun extract_moduledoc0/2,
+                                     fun extract_module_meta/2,
+                                     fun extract_exported_funs/2,
+                                     fun extract_file/2,
                                      fun extract_record/2,
-                                     fun extract_hidden_types0/2, %done
-                                     fun extract_type_defs0/2,    %done
+                                     fun extract_hidden_types0/2,
+                                     fun extract_type_defs0/2,
                                      fun extract_type_dependencies/2],
                              foldl(fun (F, State1) -> F(AST0, State1) end, State0, Funs)
                        end,

bootstrap/lib/compiler/ebin/beam_disasm.beam

@@ -692,6 +692,10 @@ value are listed.
   specification (or contract) for an exported function is not given. Use this
   option to turn on this kind of warning.
 
+- **`warn_missing_spec_documented`** - By default, warnings are not emitted when a
+  specification (or contract) for a documented function is not given. Use this
+  option to turn on this kind of warning.
+
 - **`warn_missing_spec_all`** - By default, warnings are not emitted when a
   specification (or contract) for an exported or unexported function is not
   given. Use this option to turn on this kind of warning.

bootstrap/lib/compiler/ebin/beam_doc.beam

@@ -181,7 +181,7 @@ RELSYSDIR = $(RELEASE_PATH)/compiler_test
 # ----------------------------------------------------
 
 ERL_MAKE_FLAGS +=
-ERL_COMPILE_FLAGS += +clint +clint0 +ssalint
+ERL_COMPILE_FLAGS += +clint +clint0 +ssalint +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$(ERL_COMPILE_FLAGS))
 
 EBIN = .

bootstrap/lib/compiler/ebin/beam_flatten.beam

@@ -118,7 +118,7 @@ hide_moduledoc2(Conf) ->
     ModuleName = ?get_name(),
     {ok, ModName} = default_compile_file(Conf, ModuleName),
     {ok, {docs_v1, _,_, _Mime, hidden, _,
-          [{{function,handle_call,1},{19,2},[<<"handle_call/1">>],hidden,#{}},
+          [{{function,handle_call,1},{16,2},[<<"handle_call/1">>],hidden,#{}},
            {{function, main, 0}, _, [<<"main()">>], hidden, #{}}]}} = code:get_doc(ModName),
     ok.
 
@@ -201,10 +201,10 @@ types_and_opaques(Conf) ->
            UsesPublic, Ignore, MapFun, PrivateEncoding, Foo
           ]}} = code:get_doc(ModName),
 
-    {{type,public,0},{128,2},[<<"public()">>],none,#{exported := true}} = Public,
-    {{type,intermediate,0},{127,2},[<<"intermediate()">>],none,#{exported := false}} = Intermediate,
-    {{type,hidden_nowarn_type,0},{123,2},[<<"hidden_nowarn_type()">>],hidden,#{exported := false}} = HiddenNoWarnType,
-    {{type,hidden_type,0},{120,2},[<<"hidden_type()">>],hidden,#{exported := false}} = HiddenType,
+    {{type,public,0},{125,2},[<<"public()">>],none,#{exported := true}} = Public,
+    {{type,intermediate,0},{124,2},[<<"intermediate()">>],none,#{exported := false}} = Intermediate,
+    {{type,hidden_nowarn_type,0},{120,2},[<<"hidden_nowarn_type()">>],hidden,#{exported := false}} = HiddenNoWarnType,
+    {{type,hidden_type,0},{117,2},[<<"hidden_type()">>],hidden,#{exported := false}} = HiddenType,
     {{type,my_other_private_type,0},MyOtherPrivateTypeLine,
               [<<"my_other_private_type()">>],none,#{exported := false}} = OtherPrivateType,
     {{type,my_private_type,0},MyPrivateTypeLine,
@@ -230,22 +230,22 @@ types_and_opaques(Conf) ->
     {{type, name,1},_,[<<"name(_)">>], TypeDoc, #{exported := true}} = Name,
     {{type, hidden_included_type, 0}, _, _, hidden, #{exported := false }} = HiddenIncludedType,
 
-    {{function,uses_public,0},{131,1},[<<"uses_public()">>],none,#{}} = UsesPublic,
+    {{function,uses_public,0},{128,1},[<<"uses_public()">>],none,#{}} = UsesPublic,
     {{function,ignore_type_from_hidden_fun,0},_,[<<"ignore_type_from_hidden_fun()">>],hidden,#{}} = Ignore,
     {{function,map_fun,0},_,[<<"map_fun()">>],none,#{}} = MapFun,
     {{function,private_encoding_func,2},_,[<<"private_encoding_func(Data, Options)">>],none,#{}} = PrivateEncoding,
     {{function,foo,0},_,[<<"foo()">>],none,#{}} = Foo,
 
-    ?assertEqual(106, erl_anno:line(MyOtherPrivateTypeLine)),
-    ?assertEqual(105, erl_anno:line(MyPrivateTypeLine)),
-    ?assertEqual(102, erl_anno:line(MyMapLine)),
-    ?assertEqual(99, erl_anno:line(StateEnterLine)),
-    ?assertEqual(98, erl_anno:line(CallbackModeLine)),
-    ?assertEqual(96, erl_anno:line(CallbackResultLine)),
+    ?assertEqual(103, erl_anno:line(MyOtherPrivateTypeLine)),
+    ?assertEqual(102, erl_anno:line(MyPrivateTypeLine)),
+    ?assertEqual(99, erl_anno:line(MyMapLine)),
+    ?assertEqual(96, erl_anno:line(StateEnterLine)),
+    ?assertEqual(95, erl_anno:line(CallbackModeLine)),
+    ?assertEqual(93, erl_anno:line(CallbackResultLine)),
 
     [{File, Ws}, {HrlFile, HrlWs}] = Warnings,
     ?assertEqual("types_and_opaques.erl", filename:basename(File)),
-    ?assertEqual({{120,2}, beam_doc,
+    ?assertEqual({{117,2}, beam_doc,
                   {hidden_type_used_in_exported_fun,{hidden_type,0}}}, lists:nth(4, Ws)),
 
     ?assertEqual("types_and_opaques.hrl", filename:basename(HrlFile)),
@@ -550,10 +550,10 @@ spec_switch_order(Conf) ->
 
     {ok, {docs_v1, _ModuleAnno,_, _, _, _,
           [NotFalse, Other, Bar, Foo]}} = code:get_doc(ModName),
-  {{function,not_false,0}, {53,1}, [<<"not_false()">>], none,#{}} = NotFalse,
-  {{function,other,0},{37,2},[<<"other()">>],hidden,#{}} = Other,
-  {{function,bar,1},{31,2},[<<"bar(X)">>],hidden,#{}} = Bar,
-  {{function,foo,1}, {23, 2}, [<<"foo(Var)">>], #{ <<"en">> := <<"Foo does X">> }, #{}} = Foo.
+  {{function,not_false,0}, {52,1}, [<<"not_false()">>], none,#{}} = NotFalse,
+  {{function,other,0},{36,2},[<<"other()">>],hidden,#{}} = Other,
+  {{function,bar,1},{30,2},[<<"bar(X)">>],hidden,#{}} = Bar,
+  {{function,foo,1}, {22, 2}, [<<"foo(Var)">>], #{ <<"en">> := <<"Foo does X">> }, #{}} = Foo.
 
 skip_doc(Conf) ->
   ModuleName =?get_name(),

bootstrap/lib/compiler/ebin/beam_jump.beam

@@ -4,9 +4,6 @@
 
 -moduledoc hidden.
 
--doc "
-Doc test module
-".
 -doc hidden.
 main() ->
     ok().

bootstrap/lib/compiler/ebin/beam_listing.beam

@@ -2,7 +2,6 @@
 
 -export([foo/1, bar/1, other/0, not_false/0]).
 
--doc hidden.
 -spec foo(integer()) -> mytype().
 
 

bootstrap/lib/compiler/ebin/beam_opcodes.beam

@@ -57,9 +57,6 @@ Represents a maybe type.
 -type hidden_false() :: atom().
 
 -doc false.
--doc "
-Here is ok.
-".
 -type hidden() :: hidden_false().
 
 
@@ -131,17 +128,8 @@ ignore_type_from_hidden_fun() ->
 uses_public() ->
     qux().
 
--doc false.
 -doc "
-Hidden function with doc attribute
+Un-exported function with doc attribute
 ".
 qux() ->
-    qux2().
-
-
--doc "
-Hidden function with doc attribute
-".
--doc false.
-qux2() ->
     ok.

bootstrap/lib/compiler/ebin/beam_ssa.beam

@@ -72,7 +72,7 @@ RELSYSDIR = $(RELEASE_PATH)/debugger_test
 # ----------------------------------------------------
 
 ERL_MAKE_FLAGS +=
-ERL_COMPILE_FLAGS +=
+ERL_COMPILE_FLAGS += +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$(ERL_COMPILE_FLAGS))
 
 EBIN = .

bootstrap/lib/compiler/ebin/beam_ssa_alias.beam

@@ -593,18 +593,17 @@ run(Opts) ->
     Warnings :: [dial_warning()],
     ModulesAnalyzed :: [module()].
 
+run_report_modules_analyzed(Opts) ->
+  {Warnings, _ModulesChanged, ModulesAnalyzed} = run_report_modules_changed_and_analyzed(Opts),
+  {Warnings, ModulesAnalyzed}.
+
 -doc false.
 -spec run_report_modules_changed_and_analyzed(Options) -> {Warnings, ModulesChanged, ModulesAnalyzed} when
     Options :: [dial_option()],
     Warnings :: [dial_warning()],
     ModulesChanged :: undefined | [module()],
     ModulesAnalyzed :: [module()].
 
-run_report_modules_analyzed(Opts) ->
-  {Warnings, _ModulesChanged, ModulesAnalyzed} = run_report_modules_changed_and_analyzed(Opts),
-  {Warnings, ModulesAnalyzed}.
-
--doc false.
 run_report_modules_changed_and_analyzed(Opts) ->
   try dialyzer_options:build([{report_mode, quiet},
 			      {erlang_mode, true}|Opts]) of

bootstrap/lib/compiler/ebin/beam_ssa_bc_size.beam

@@ -115,6 +115,7 @@ ERL_COMPILE_FLAGS += \
 	+'{attribute,insert,app_vsn,"$(APP_VSN)"}' \
 	+warn_export_vars \
 	+warn_unused_vars \
+	+nowarn_missing_spec_documented \
 	-pa $(ABS_EBIN) \
 	-I $(INCDIR) \
 	-I gen \

bootstrap/lib/compiler/ebin/beam_ssa_bool.beam

@@ -55,6 +55,7 @@ DATA_DIRS = $(sort $(dir $(DATA)))
 # This is only used to compile suite locally when running with a
 # target like 'all' below. Target release_tests only installs source.
 ERL_COMPILE_FLAGS += +warn_export_vars \
+		     +nowarn_missing_spec_documented \
                      +warn_unused_vars \
                      -I ../include \
                      -I ../src/gen \

bootstrap/lib/compiler/ebin/beam_ssa_bsm.beam

@@ -23,7 +23,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/edoc-$(VSN)
 
 EBIN = ../ebin
 XMERL = ../../xmerl
-ERL_COMPILE_FLAGS += -pa $(XMERL) -I../include -I$(XMERL)/include +warn_unused_vars +nowarn_shadow_vars +warn_unused_import +warn_deprecated_guard +no_docs
+ERL_COMPILE_FLAGS += -pa $(XMERL) -I../include -I$(XMERL)/include +warn_unused_vars +nowarn_shadow_vars +warn_unused_import +warn_deprecated_guard +no_docs +nowarn_missing_spec_documented
 
 include files.mk
 

bootstrap/lib/compiler/ebin/beam_ssa_check.beam

@@ -26,7 +26,7 @@ RELSYSDIR = $(RELEASE_PATH)/edoc_test
 # ----------------------------------------------------
 
 ERL_MAKE_FLAGS += 
-ERL_COMPILE_FLAGS +=
+ERL_COMPILE_FLAGS += +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$(ERL_COMPILE_FLAGS))
 
 EBIN = .

bootstrap/lib/compiler/ebin/beam_ssa_codegen.beam

@@ -60,7 +60,7 @@ APP_TARGET = $(EBIN)/$(APP_FILE)
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_COMPILE_FLAGS += -I../include -I../ebin -Werror
+ERL_COMPILE_FLAGS += -I../include -I../ebin -Werror +nowarn_missing_spec_documented
 
 # ----------------------------------------------------
 # Targets

bootstrap/lib/compiler/ebin/beam_ssa_dead.beam

@@ -54,7 +54,7 @@ RELSYSDIR = $(RELEASE_PATH)/eldap_test
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_COMPILE_FLAGS += $(INCLUDES) -pa $(ERL_TOP)/lib/eldap/ebin
+ERL_COMPILE_FLAGS += $(INCLUDES) -pa $(ERL_TOP)/lib/eldap/ebin +nowarn_missing_spec_documented
 ERL_COMPILE_FLAGS := $(filter-out +deterministic,$(ERL_COMPILE_FLAGS))
 
 EBIN = .

bootstrap/lib/compiler/ebin/beam_ssa_destructive_update.beam

@@ -55,7 +55,7 @@ TARGET_FILES= $(MODULES:%=$(EBIN)/%.$(EMULATOR))
 # ----------------------------------------------------
 # FLAGS
 # ----------------------------------------------------
-ERL_COMPILE_FLAGS += -pa ../../et/ebin +nowarn_missing_doc
+ERL_COMPILE_FLAGS += -pa ../../et/ebin +nowarn_missing_doc +nowarn_missing_spec_documented
 EBIN = .
 
 # ----------------------------------------------------