[AttrDocs]: document gnu_inline function attribute

[nickdesaulniers]

Summary

This wasn't documented https://clang.llvm.org/docs/AttributeReference.html, and briefly mentioned https://clang.llvm.org/docs/UsersManual.html#differences-between-various-standard-modes.

[nickdesaulniers]

• link to correct doc

[nickdesaulniers]

• explicitly mention extern inline

[efriedma]

Thanks for taking the time to write documentation.

The phrase "C89 convention" is misleading; the original ISO C standard doesn't define the inline keyword at all. Maybe something along the lines of "GNU inline extension". And maybe mention it's the default with -std=gnu89.

[nickdesaulniers]

• s/c89/GNU inline extension/g and mention -std=gnu89/-fgnu89-inline

[rsmith]

include/clang/Basic/AttrDocs.td

3514–3516

This description is neither entirely correct nor complete. gnu_inline means:

• If any declaration that is declared inline is not declared extern, then the inline keyword is just a hint (note that this is different from the behavior of inline in both C99 inline semantics and C++ inline semantics)
• If all declarations that are declared inline are also declared extern, then the function body is present only for inlining and no out-of-line version is emitted

And in particular as special cases, static inline emits an out-of-line version if needed, a plain inline definition emits an out-of-line version always, and an extern inline definition (in a header) followed by a (non-extern) inline declaration in a source file emits an out-of-line version of the function in that source file but provides the function body for inlining to all includers of the header.

Please capitalize the C in C99.

3518–3522

It would make sense to also mention __GNUC_GNU_INLINE__ here, and that exactly one of these two macros will be defined for any compilation (although the macros are meaningless in C++ and should not be used there).

3524

This is the default behavior for all pre-C99 C compilations, notably including -std=c89 (and -std=c94).

[nickdesaulniers]

• Take rsmith's sugguested wording. Add info about GNUC_STDC_INLINE.

[rsmith]

include/clang/Basic/AttrDocs.td

3518

Might be useful to be a bit more explicit about how it differs:

[...] is just a hint. In particular, an out-of-line definition is still emitted for a function with external linkage even if all call sites are inlined, unlike in C99 inline semantics and C++ inline semantics.

3524

Maybe replace the "And in particular as special cases," with "Some important consequences:"

3536

I'd add: "It is unspecified which macro is defined in a C++ compilation."

(In practice, Clang always defines the GNU_INLINE macro, as do very old versions of GCC. More recent versions of GCC define GNU_INLINE in C++98 mode and STDC_INLINE in C++11 mode onwards, despite C++98 and C++11 having identical inline semantics. I don't think we want to give any guarantees about our behavior here.)

[nickdesaulniers]

• link to correct doc
• explicitly mention extern inline
• s/c89/GNU inline extension/g and mention -std=gnu89/-fgnu89-inline
• Take rsmith's sugguested wording. Add info about GNUC_STDC_INLINE.
• some final touches recommended by rsmith

[rsmith]

Looks good, thanks for improving our documentation!

[rupprecht]

BTW, seems like these docs have tests that weren't updated. Fixed with rL341002, but please take a look if that's not the right fix.

include/clang/Basic/Attr.td

def FormatArg : InheritableAttr {
   let Args = [ParamIdxArgument<"FormatIdx">];
   let Subjects = SubjectList<[ObjCMethod, HasFunctionProto]>;
   let Documentation = [Undocumented];
 }
 
 def GNUInline : InheritableAttr {
   let Spellings = [GCC<"gnu_inline">];
   let Subjects = SubjectList<[Function]>;
-  let Documentation = [Undocumented];
+  let Documentation = [GnuInlineDocs];
 }
 
 def Hot : InheritableAttr {
   let Spellings = [GCC<"hot">];
   let Subjects = SubjectList<[Function]>;
   // An AST node is created for this attribute, but not actually used beyond
   // semantic checking for mutual exclusion with the Cold attribute.
   let Documentation = [Undocumented];

include/clang/Basic/AttrDocs.td

def NoDestroyDocs : Documentation {
   let Category = DocCatVariable;
   let Content = [{
 The ``no_destroy`` attribute specifies that a variable with static or thread
 storage duration shouldn't have its exit-time destructor run. Annotating every
 static and thread duration variable with this attribute is equivalent to
 invoking clang with -fno-c++-static-destructors.
   }];
 }
+
+def GnuInlineDocs : Documentation {
+  let Category = DocCatFunction;
+  let Content = [{
+The ``gnu_inline`` changes the meaning of ``extern inline`` to use GNU inline
+semantics, meaning:
+
+* If any declaration that is declared ``inline`` is not declared ``extern``,
+then the ``inline`` keyword is just a hint. In particular, an out-of-line
+definition is still emitted for a function with external linkage, even if all
+call sites are inlined, unlike in C99 and C++ inline semantics.
+
+* If all declarations that are declared ``inline`` are also declared
+``extern``, then the function body is present only for inlining and no
+out-of-line version is emitted.
+
+Some important consequences: ``static inline`` emits an out-of-line
+version if needed, a plain ``inline`` definition emits an out-of-line version
+always, and an ``extern inline`` definition (in a header) followed by a
+(non-``extern``) ``inline`` declaration in a source file emits an out-of-line
+version of the function in that source file but provides the function body for
+inlining to all includers of the header.
+
+Either ``__GNUC_GNU_INLINE__`` (GNU inline semantics) or
+``__GNUC_STDC_INLINE__`` (C99 semantics) will be defined (they are mutually
+exclusive). If ``__GNUC_STDC_INLINE__`` is defined, then the ``gnu_inline``
+function attribute can be used to get GNU inline semantics on a per function
+basis. If ``__GNUC_GNU_INLINE__`` is defined, then the translation unit is
+already being compiled with GNU inline semantics as the implied default. It is
+unspecified which macro is defined in a C++ compilation.
+
+GNU inline semantics are the default behavior with ``-std=gnu89``,
+``-std=c89``, ``-std=c94``, or ``-fgnu89-inline``.
+  }];
+}