doc: clarify api design guidelines for optional API

There has been discussion about whether invocations of optional API
that has been disabled should:

1. result in a link-time error because the API implementation is not
provided; or

2. result in a run-time error by having a trivial implementation that
returns -ENOTSUP.

Clarify that the intent of the guideline is that a link-time error
should be produced.  The rationale is that it is too easy to disable
the option at build time, and not discover it because the application
fails to check for a `-ENOTSUP` return.

Signed-off-by: Peter Bigot <[email protected]>

Author: pabigot

doc/guides/design_guidelines.rst

@@ -87,8 +87,9 @@ practices should be followed.
   enabled should be provided unconditionally.  Add a note in the
   description that the function is available only when the specified
   feature is enabled, referencing the required Kconfig symbol by name.
-  (In cases where the function is used but not enabled a link-time error
-  will be generated.)
+  In the cases where the function is used but not enabled the definition
+  of the function shall be excluded from compilation, so references to
+  the unsupported API will result in a link-time error.
 * Where code specific to the feature is isolated in a source file that
   has no other content that file should be conditionally included in
   ``CMakeLists.txt``::