Our set of warnings in PSPDFKit

gistfile1.txt

//
//  Warnings.xcconfig
//
//  The list of warnings we (don’t) use, and the reasons why.
//
// :MARK: Warnings in use:
//	:MARK: -everything
//		We want the best possible diagnostics, so we simply enable everything that exists, and then opt–out of what doesn’t make sense for us.
//
// :MARK: - Warnings not to be promoted:
//	Even if a project sets ``-Werror``, the following shall not be promoted to errors:
//	:MARK: -deprecated-declarations
//		Even if some API is deprecated, we may still need to call it for compatibility reasons.
//		Thus, we cannot allow this warning to become promoted to an error.
//	:MARK: -deprecated-implementations
//		Deprecations are necessary, and useful to signal (pending) API changes.
//		For compatibility reasons, it may still be necessary to implement, and even override those methods, though.
//
// :MARK: - Warnings that have been disabled:
//	:MARK: -objc-missing-property-synthesis
//		This isn’t a real issue since we don’t have any interest in building on extremely old Clangs.
//		(Also, each property that cannot be auto–synthesized triggers at least a warning…)
//	:MARK: -unused-parameter
//		While this is generally desirable to prevent a subvariaty of typo–bugs, enabling this warning now would mean **a lot** of noise. => Disabled for now.
//	:MARK: -covered-switch-default
//		This would emit a warning for every use of a default label, however since C can't guarantee that an integer type used as enum *only* contains valid enum values, we need default labels.
//	:MARK: -direct-ivar-access
//      This is a mid-term project. We currently use a lot of direct ivar access. Sometimes explicitely, sometimes just because there's code from iOS 4 where dispatch types were not yet objects, or because there's mixed code style in it.
//		TODO: Why, actually? To much noise?
//	:MARK: -assign-enum
//		Disabling this would require casting enum option values instead of using 0 to indicate not special setting.
//      For example: (NSEnumerationOptions)kNilOptions (since there is no NSEnumerationOptionNone)
//      Where bit masks are used, a cast would be required in any case (UIViewAnimationOptions).
//	:MARK: -float-equal
//      While we could change all 90 instances of floating point comparison to a method that includes an epsilon, this is overkill and not needed.
//		See http://stackoverflow.com/questions/11421756/weverything-yielding-comparing-floating-point-with-or-is-unsafe
//	:MARK: -vla
//		Variable length arrays are a feature of C99 and used in some places.
//      There's no reason to disallow this useful feature, when used in moderation. It also works with C++:
//      http://clang.llvm.org/compatibility.html#vla
//	:MARK: -pedantic
//		Too. Much. Noise.
//	:MARK: -documentation-unknown-command
//		Even though Xcode correctly highlights certain documentation directives, (like e.g. `@throws`) it does not seem to know them internally.
//		Since these annotations are still useful, we don’t want them to become warnings.
//	:MARK: -packed
//		Disabling this warning appears to be necessary because of a bug reported against Clang in late 2013 (http://llvm.org/bugs/show_bug.cgi?id=18132).
//		It only triggers in Vendor/lz4.c, but since the flag is defective there’s no point in enabling it.
//	:MARK: -padded
//		This isn’t really an issue to us, since we’re not programming embedded systems.
//	:MARK: -auto-import
//		Standard ``import`` is used by tons of files we import ourselves. => Disabled.
//  :MARK: -selector
//      This warning requires that a selector with the name passed into `@selector()` is implemented in that same translation unit.
//      Which is counter to the primary use case for that construct: `respondsToSelector:` checks.
//	:MARK: -receiver-is-weak
//		This needs some thorough discussion, and thinking through:
//		As far as I know, sending a message to a weak receiver — just as any access to a weak variable — causes the compiler to emit a call to `objc_storeStrong()` call, that prevents the situation being warned against here.
//		It may however be the case that the compiler can remove this call during optimization under certain conditions, which _could_ then lead to the receiver actually becoming `nil` due to some sort of race–condition, because the last strong reference to this object is being released on another thread, which — in turn — would cause the story–book example of a Heisenbug.
//  :MARK: -sign-conversion
//      There are a couple of extremely subtle bugs that lure behind this warning, but most of these are very unlikely to happen.
//      Given that there’s a ton of code that uses NSIndexPath, and implements <UITableViewDataSource> which unfortunately use signed integers as parameters/return–values for API that uses unsigned integers, this is simply too much noise.
//  :MARK: -Wno-auto-import
//      There are still a few Clang issues around @import for frameworks and also if C++ is used. We can't yet use it so we will ignore the warning that #import is automatically convertedf to @import.
//  :MARK: -Wno-incomplete-module
//      Produces module map warnings on Apple frameworks in the test bundle (https://github.com/PSPDFKit/PSPDFKit/issues/2572). Disabling until a better solution is available. The warnings do not seem to impact the functionality.
// :MARK: -Wno-c99-extensions, -Wvla-extension
//      The C99 extensions are very useful, also when using Objective-C++.

WARNING_CFLAGS = -Weverything -Wno-error-deprecated-declarations -Wno-error-deprecated-implementations -Wno-objc-missing-property-synthesis -Wno-unused-parameter -Wno-covered-switch-default -Wno-direct-ivar-access -Wno-assign-enum -Wno-float-equal -Wno-vla -Wno-documentation-unknown-command -Wno-packed -Wno-padded -Wno-auto-import -Wno-selector -Wno-receiver-is-weak -Wno-sign-conversion -Wno-auto-import -Wno-static-in-inline -Wno-gnu-conditional-omitted-operand -Wno-gnu-zero-variadic-macro-arguments -Wno-gnu-statement-expression -Wno-language-extension-token -Wno-pointer-arith -Wno-empty-translation-unit -Wno-format-non-iso -Wno-comment -Wno-gnu-folding-constant -Wno-c++98-compat-pedantic -Wno-c++98-compat -Wno-old-style-cast -Wno-incomplete-module -Wno-vla-extension -Wno-c99-extensions -Wno-cstring-format-directive -Rno-module-build

Something doesn’t line up there:
-Wdocumentation and -Wno-documentation.

@danyowdee true, fixed. Thanks!