documentation clarifications on dynamic dispatch/HWY_ATTR. Refs #1005

PiperOrigin-RevId: 481620845

Author: jan-wassenberg

README.md

@@ -167,8 +167,8 @@ Due to ADL restrictions, user code calling Highway ops must either:
     hn::Add()`; or
 *   add using-declarations for each op used: `using hwy::HWY_NAMESPACE::Add;`.
 
-Additionally, each function that calls Highway ops must either be prefixed with
-`HWY_ATTR`, OR reside between `HWY_BEFORE_NAMESPACE()` and
+Additionally, each function that calls Highway ops (such as `Load`) must either
+be prefixed with `HWY_ATTR`, OR reside between `HWY_BEFORE_NAMESPACE()` and
 `HWY_AFTER_NAMESPACE()`. Lambda functions currently require `HWY_ATTR` before
 their opening brace.
 
@@ -190,6 +190,27 @@ they use static or dynamic dispatch.
     [quick-reference](g3doc/quick_reference.md)) if `HWY_TARGET_INCLUDE` is
     defined and `foreach_target.h` is included.
 
+When using dynamic dispatch, `foreach_target.h` is included from translation
+units (.cc files), not headers. Headers containing vector code shared between
+several translation units require a special include guard, for example the
+following taken from `examples/skeleton-inl.h`:
+
+```
+#if defined(HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_) == defined(HWY_TARGET_TOGGLE)
+#ifdef HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
+#undef HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
+#else
+#define HIGHWAY_HWY_EXAMPLES_SKELETON_INL_H_
+#endif
+
+#include "hwy/highway.h"
+// Your vector code
+#endif
+```
+
+By convention, we name such headers `-inl.h` because their contents (often
+function templates) are usually inlined.
+
 ## Compiler flags
 
 Applications should be compiled with optimizations enabled - without inlining,

g3doc/quick_reference.md

@@ -49,7 +49,9 @@ The public headers are:
 *   hwy/tests/test_util-inl.h: defines macros for invoking tests on all
     available targets, plus per-target functions useful in tests.
 
-SIMD implementations must be preceded and followed by the following:
+Highway provides helper macros to simplify your vector code and ensure support
+for dynamic dispatch. To use these, add the following to the start and end of
+any vector code:
 
 ```
 #include "hwy/highway.h"
@@ -65,6 +67,10 @@ namespace HWY_NAMESPACE {
 HWY_AFTER_NAMESPACE();
 ```
 
+If you choose not to use the `BEFORE/AFTER` lines, you must prefix any function
+that calls Highway ops such as `Load` with `HWY_ATTR`. You can omit the
+`HWY_NAMESPACE` lines if not using dynamic dispatch.
+
 ## Notation in this doc
 
 *   `T` denotes the type of a vector lane (integer or floating-point);