[cfe-commits] [PATCH] Documentation diagnostics: warn on duplicate commands

[Douglas Gregor]

On Aug 3, 2012, at 11:04 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> Hello,
> 
> Doxygen manual claims that multiple \brief or \returns commands will
> be merged together, but actual behavior is different (second \brief
> command becomes a part of a discussion, second \returns becomes a
> "Returns: blah" paragraph on its own).  Anyway, it seems to be a bad
> idea to use multiple \brief or \returns commands in a single command.
> 
> Attached is a patch that implements this diagnostic.


I think it's completely reasonable to warn about this. If users start to complain, we can back off :)

Some wording nits:

+def warn_doc_block_command_duplicate : Warning<
+  "command '\\%0' is duplicate">,
+  InGroup<Documentation>, DefaultIgnore;
+

How about "duplicated command '\\%0'"?

+def note_doc_block_command_previous : Note<
+  "previous command here">;
+
+def note_doc_block_command_aliases : Note<
+  "commands '\\%0' and '\\%1' are aliases">;

Can we merge these together, so that the 'duplicate' warning doesn't end up with two notes? For example:

+def note_doc_block_command_previous : Note<
+  "previous command '\\%0' here">;
+
+def note_doc_block_command_previous_alias : Note<
+  "previous command '\\%1' (an alias of '\\%0') here">;

Thanks!

	- Doug