[hawkmoth] Re: [PATCH v2 2/3] hawkmoth: add support for propagating diagnostics

  • From: Bruno Santos <brunomanuelsantos@xxxxxxxxxxxxxxxxxx>
  • To: hawkmoth@xxxxxxxxxxxxx
  • Date: Wed, 1 May 2019 17:37:27 +0200

On 15:46:34 2019-05-01, Marius Vlad wrote:

On Wed, May 01, 2019 at 02:01:59PM +0200, Bruno Santos wrote:
On 12:21:20 2019-05-01, Marius Vlad wrote:
On Wed, May 01, 2019 at 12:28:37AM +0200, Bruno Santos wrote:
+class ErrorLevel(enum.Enum):
+    """
+    Supported error levels in inverse numerical order of severity. The 
values
+    are chosen so that they map directly to a 'verbosity level'.
+    """
+    ERROR = 0
+    WARNING = 1
+    INFO = 2
+    DEBUG = 3

Is there a reason not to include all? (FATAL/NOTE)...

The current proposal is:

- ERROR: Something went terribly wrong, documentation is likely broken.

- WARNING: May have affected the documentation output in subtle ways.
  Maybe some symbol is not fully defined and therefore won't be linked.
  Documentation is still sound though.

- INFO: Tangentially related to documentation, but of no consequence to
  the output. E.g. 'entering file xxx', 'found function token', etc.

- DEBUG: Don't affect documentation, but may be important in inspecting
  what the code is doing for debug/development purposes. E.g. some
  lesser error from an external module that we discarded.

I don't see what FATAL and NOTE would bring to the table.

If we really get a lot more errors and must discriminate further, I'd
argue for an horizontal expansion rather than vertical: (e.g.) -wclang,
etc. Adding more levels won't really help in my opinion.

I believe this all make sense, I was merely asking why we don't follow
exactly the clang types, giving the mapping. 

We can debate whether Hawkmoth needs those extra levels of course, but
Clang having them is not a good reason in my view. Outside of
clang_diagnostics, I wouldn't pay any attention to what Clang is doing
in this matter.

My point above is that, from Hawkmoth's perspective, I anticipate no
need for any other level and we can also add them later if we find
they're missing. Don't mind too much to be overruled though.


Side-note: Diagnostics from clang will emit a fatal when files are not
found, and error if can't resolve data type.  In our source code,
headers missing combined with function attributes will result in
symbols (functions) not being printed/showed and only the
comment is be present. Currently we tag this as ERROR, yet
documentation is rather sound, but your opinion here might
differ.  Just want to make sure this behaviour is known.

Hmm, our definition of soundness is different then. Indeed the
documentation may be valid reST, but if it was not consistent with the
expected result, it must be broken, hence the error. That's how I see it
anyway.

Cheers,
Bruno

Attachment: signature.asc
Description: PGP signature

Other related posts:

  1. Home
  2. hawkmoth
  3. Archive
  4. 05-2019