System header <sys/vnode_if.h> generates >200 documentation warnings

Originator:rsfinn
Number:rdar://30060885 Date Originated:2017-01-17
Status:Open Resolved:
Product:Developer Tools Product Version:Xcode 8.2.1
Classification:3 - Medium Reproducible:Always
 
Summary:
Including the system header file <sys/vnode.h> in a C++ header or source file (as when implementing an IOKit device driver) generates over 200 warnings, including the following:

// ...
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk/System/Library/Frameworks/Kernel.framework/Headers/sys/vnode_if.h:920:3: '@return' command used in a comment that is not attached to a function or method declaration
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk/System/Library/Frameworks/Kernel.framework/Headers/sys/vnode_if.h:934:3: '@function' command should be used in a comment attached to a function declaration
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.12.sdk/System/Library/Frameworks/Kernel.framework/Headers/sys/vnode_if.h:941:3: '@param' command used in a comment that is not attached to a function declaration
// ...

As the error messages indicate, the actual problem is within the system header file <sys/vnode_if.h>.  Examining this file suggests that the problem is caused by the documentation comment block being separated from the function declaration by one or more blank lines.

Although this problem can be worked around, it is quite annoying and can be easily addressed by Apple.

Steps to Reproduce:
1. Create an Xcode project of type "Generic Kernel Extension".
2. In the main .c file created by the project template, insert the following line after the last #include directive:

#include <sys/vnode_if.h>

3. Build the project.

Expected Results:
The project should build without errors or warnings.

Actual Results:
The compiler generates 200 warnings about various documentation issues, plus a final warning indicating that no more than 200 warnings will be emitted.

Version:
macOS 10.12.2 (16C67)

Notes:
It is possible to work around the issue by using the "clang diagnostic" pragma, as follows:

#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdocumentation"
#include <sys/vnode.h>
#pragma clang diagnostic pop

Configuration:
Xcode 8.2.1 (8C1002)
macOS 10.12 SDK

Comments

Still in Xcode 9 beta 6

The problem still exists in Xcode version 9.0 beta 6 (9M214v), using the macOS 10.13 SDK. Again, the issue is with the version of within Kernel.framework.

More precisely, this applies to the version of present in the Kernel framework. The original report was unclear about this.

The problem appears to remain in the SDK shipped with Xcode 8.3.


Please note: Reports posted here will not necessarily be seen by Apple. All problems should be submitted at bugreport.apple.com before they are posted here. Please only post information for Radars that you have filed yourself, and please do not include Apple confidential information in your posts. Thank you!