[llvm-bugs] [Bug 32667] New: -Wdocumentation doesn't let one document function pointers in a struct

[via llvm-bugs]

https://bugs.llvm.org/show_bug.cgi?id=32667

            Bug ID: 32667
           Summary: -Wdocumentation doesn't let one document function
                    pointers in a struct
           Product: clang
           Version: 4.0
          Hardware: PC
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P
         Component: Frontend
          Assignee: unassignedclangbugs at nondot.org
          Reporter: gpakosz at pempek.net
                CC: llvm-bugs at lists.llvm.org

Hello,

Our headers contain struct definitions with function pointers. These structs
are semantically interfaces we want to document. There are many, hence we don't
typedef things (which clang supports).

struct X
{
  /**
   * Foo!
   *
   * @param i an integer.
   * @return another integer.
   */
  int (*foo)(int i);
};

int main()
{
  return 0;
}

This sample warns with:
<main.c>:6:7: warning: '\param' command used in a comment that is not attached
to a function declaration [-Wdocumentation]
   * @param i an integer.
      ^~~~~
<main.c>:7:7: warning: '\return' command used in a comment that is not attached
to a function or method declaration [-Wdocumentation]
   * @return another integer.
     ~^~~~~~~~~~~~~~~~~~~~~~~
2 warnings generated.
Compiler exited with result code 0

It seems that since 3.2, clang never supported documenting function pointers
inside structs.

You can see it in action here: https://godbolt.org/g/zXkigH

Thanks for reading,
G.

-- 
You are receiving this mail because:
You are on the CC list for the bug.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-bugs/attachments/20170414/f8f5569d/attachment.html>