modelize: `missing-doc` on attributes

[nit.git] / src / toolcontext.nit

diff --git a/src/toolcontext.nit b/src/toolcontext.nit
index 95b6e9b..64549ad 100644 (file)
--- a/src/toolcontext.nit
+++ b/src/toolcontext.nit
@@ -149,10 +149,42 @@ class ToolContext
                check_errors
        end
 
-       # Display a warning
+       # Display a first-level warning.
+       #
+       # First-level warnings are warnings that SHOULD be corrected,
+       # and COULD usually be immediately corrected.
+       #
+       # * There is a simple correction
+       # * There is no reason to let the code this way (no reasonable @supresswarning-like annotation)
+       # * They always are real issues (no false positive)
+       #
+       # First-level warnings are displayed by default (except if option `-q` is given).
        fun warning(l: nullable Location, tag: String, text: String)
        do
-               if opt_warn.value == 0 then return
+               if opt_warning.value.has("no-{tag}") then return
+               if not opt_warning.value.has(tag) and opt_warn.value == 0 then return
+               messages.add(new Message(l, tag, text))
+               warning_count = warning_count + 1
+               if opt_stop_on_first_error.value then check_errors
+       end
+
+       # Display a second-level warning.
+       #
+       # Second-level warnings are warnings that should require investigation,
+       # but cannot always be immediately corrected.
+       #
+       # * The correction could be complex. e.g. require a refactorisation or an API change.
+       # * The correction cannot be done. e.g. Code that use a deprecated API for some compatibility reason.
+       # * There is not a real issue (false positive). Note that this should be unlikely.
+       # * Transitional: While a real warning, it fires a lot in current code, so a transition is needed
+       #   in order to fix them before promoting the advice to a warning.
+       #
+       # In order to prevent warning inflation à la Java, second-level warnings are not displayed by
+       # default and require an additional option `-W`.
+       fun advice(l: nullable Location, tag: String, text: String)
+       do
+               if opt_warning.value.has("no-{tag}") then return
+               if not opt_warning.value.has(tag) and opt_warn.value <= 1 then return
                messages.add(new Message(l, tag, text))
                warning_count = warning_count + 1
                if opt_stop_on_first_error.value then check_errors
@@ -197,7 +229,10 @@ class ToolContext
        var option_context: OptionContext = new OptionContext
 
        # Option --warn
-       var opt_warn: OptionCount = new OptionCount("Show warnings", "-W", "--warn")
+       var opt_warn: OptionCount = new OptionCount("Show more warnings", "-W", "--warn")
+
+       # Option --warning
+       var opt_warning = new OptionArray("Show/hide a specific warning", "-w", "--warning")
 
        # Option --quiet
        var opt_quiet: OptionBool = new OptionBool("Do not show warnings", "-q", "--quiet")
@@ -234,7 +269,7 @@ class ToolContext
 
        init
        do
-               option_context.add_option(opt_warn, opt_quiet, opt_stop_on_first_error, opt_no_color, opt_log, opt_log_dir, opt_help, opt_version, opt_set_dummy_tool, opt_verbose, opt_bash_completion)
+               option_context.add_option(opt_warn, opt_warning, opt_quiet, opt_stop_on_first_error, opt_no_color, opt_log, opt_log_dir, opt_help, opt_version, opt_set_dummy_tool, opt_verbose, opt_bash_completion)
        end
 
        # Name, usage and synopsis of the tool.