[PATCH] D146420: Document the Clang policies on claiming support for a feature

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman updated this revision to Diff 506591.
aaron.ballman marked 2 inline comments as done.
aaron.ballman added a comment.

Updating based on review feedback.

(Note: Phab seems to be confused about the changes being at the end of the file -- it claims there's no trailing context for the patch and that's what seems to disable the ability to make suggested edits.)


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

https://reviews.llvm.org/D146420

Files:
  clang/docs/InternalsManual.rst


Index: clang/docs/InternalsManual.rst
===================================================================
--- clang/docs/InternalsManual.rst
+++ clang/docs/InternalsManual.rst
@@ -3268,3 +3268,39 @@
      proper visitation for your expression, enabling various IDE features such
      as syntax highlighting, cross-referencing, and so on.  The
      ``c-index-test`` helper program can be used to test these features.
+
+Feature Test Macros
+===================
+Clang implements several ways to test whether a feature is supported or not.
+Some of these feature tests are standardized, like ``__has_cpp_attribute`` or
+``__cpp_lambdas``, while others are Clang extensions, like ``__has_builtin``.
+The common theme among all the various feature tests is that they are a utility
+to tell users that we think a particular feature is complete. However,
+completeness is a difficult property to define because features may still have
+lingering bugs, may only work on some targets, etc. We use the following
+criteria when deciding whether to expose a feature test macro (or particular
+result value for the feature test):
+
+  * Are there known issues with the feature that reject valid code?
+  * Are there known issues that accept invalid code?
+  * Are there known crashes, failed assertions, or miscompilations?
+  * Are there known issues on a particular relevant target?
+
+If the answer to any of these is "yes", the feature test macro should either
+not be defined or there should be very strong rationale for why the issues
+should not prevent defining it. Note, it is acceptable to define the feature
+test macro on a per-target basis if needed.
+
+When in doubt, being conservative is better than being aggressive. If we don't
+claim support for the feature but it does useful things, users can still use it
+and provide us with useful feedback on what is missing. But if we claim support
+for a feature that has significant bugs, we've eliminated most of the utility
+of having a feature testing macro at all because users are then forced to test
+what compiler version is in use to get a more accurate answer.
+
+The status reported by the feature test macro should always be reflected in the
+language support page for the corresponding feature (`C++
+<https://clang.llvm.org/cxx_status.html>`_, `C
+<https://clang.llvm.org/c_status.html>`_) if applicable. This page can give
+more nuanced information to the user as well, such claiming partial support for
+a feature and specifying details as to what remains to be done.


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D146420.506591.patch
Type: text/x-patch
Size: 2534 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20230320/00fc57e0/attachment.bin>