[PATCH] D76833: [CodingStandards] Document coding standard for error and warning messages

[James Henderson via Phabricator via llvm-commits]

jhenderson marked an inline comment as done.
jhenderson added inline comments.


================
Comment at: llvm/docs/CodingStandards.rst:338
+
+  error: file.o: section header 3 is corrupt. Size is 10 when it should be 20
+
----------------
dblaikie wrote:
> jhenderson wrote:
> > rnk wrote:
> > > If you look at clang diagnostics, I think most of the time we would use a semicolon to separate sentences here, so it would look like this:
> > >   error: file.o: section header 3 is corrupt; size is 10 when it should be 20
> > > 
> > > However, overall this is useful guidance, and if you want to leave this example as is for migrating existing multi-sentence diagnostics, that's OK with me.
> > Thanks for the comment. I think there's less clear consensus in the tools on what to do about mid-message ends of sentences. I know that there are several messages following `<part1>. <part2>` style and also `<part1>: <part2>` etc. Let's leave this as is for now.
> If there's lack of consensus it might be preferable for this document not to take a stance on the issue? (either drop this bit entirely, or include alternatives equally - especially if clang's convention isn't shown here (& yeah, I find "this is a fragment. This is a sentence" pretty weird/surprising - given how used to clang's conventions I am), since it's the biggest surface area/usage of diagnostics in the project)
The text itself doesn't state how to separate sentences within the messages, and this example wasn't intended to take a stance on how to form such things, but rather to illustrate that it isn't illegal to have full stops elsewhere (based on the principle that there are existing messages in that form). I think that it's also worth noting that nothing in this is intended to prevent specific projects imposing further guidelines, I guess, so I wouldn't encourage people adopting it for new clang diagnostics, I guess.

If somebody wants to go ahead and further try to get consensus on banning the use of full stops at all in diagnostic messages, I'm not going to stand in the way of that (and then this text should definitely be updated). I just don't have a strong motivation/desire to try to do so.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D76833/new/

https://reviews.llvm.org/D76833