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 10.3 (10.14 SDK) and Xcode 11.1 (10.15 SDK)

The problem still exists in Xcode versions 10.3 and 11.1 (which now generates 261 warnings).

It appears that in many cases the function declaration for which the comment header is intended no longer exists in the header file, possibly because they were stripped out or are no longer included by some auto generation mechanism that overlooks the existence of the attached documentation blocks. This continues to be annoying (although it can be worked around).

Still in Xcode 9.4.1 (10.13 SDK) and Xcode 10 beta 2 (10.14 SDK)

The problem still exists in Xcode version 9.4.1, using the macOS 10.13 SDK.

It also exists in Xcode version 10 beta 2 (10L177m), using the macOS 10.14 SDK, although in this case the 200-warning limit has apparently been raised or lifted, as a total of 256 warnings are issued.

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!