Use doc_auto_cfg on docs.rs

block-sys/CHANGELOG.md

@@ -6,6 +6,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## Unreleased - YYYY-MM-DD
 
+### Added
+* Use `doc_auto_cfg` to improve documentation output.
+
 
 ## 0.0.4 - 2022-06-13
 

block-sys/src/lib.rs

@@ -21,6 +21,8 @@
 #![warn(clippy::ptr_as_ptr)]
 // Update in Cargo.toml as well.
 #![doc(html_root_url = "https://docs.rs/block-sys/0.0.4")]
+#![cfg_attr(feature = "unstable-docsrs", feature(doc_auto_cfg, doc_cfg_hide))]
+#![cfg_attr(feature = "unstable-docsrs", doc(cfg_hide(doc)))]
 
 extern crate std;
 
@@ -58,7 +60,7 @@ pub struct Class {
 #[allow(non_camel_case_types)]
 pub type block_flags = i32;
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 pub const BLOCK_DEALLOCATING: block_flags = 0x0001;
 
 pub const BLOCK_REFCOUNT_MASK: block_flags = if cfg!(feature = "gnustep-1-7") {
@@ -73,19 +75,19 @@ pub const BLOCK_REFCOUNT_MASK: block_flags = if cfg!(feature = "gnustep-1-7") {
     0
 };
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 /// compiler
 pub const BLOCK_INLINE_LAYOUT_STRING: block_flags = 1 << 21;
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 /// compiler
 pub const BLOCK_SMALL_DESCRIPTOR: block_flags = 1 << 22;
 
-#[cfg(feature = "apple")] // Part of ABI?
+#[cfg(any(doc, feature = "apple"))] // Part of ABI?
 /// compiler
 pub const BLOCK_IS_NOESCAPE: block_flags = 1 << 23;
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 /// runtime
 pub const BLOCK_NEEDS_FREE: block_flags = 1 << 24;
 
@@ -97,7 +99,7 @@ pub const BLOCK_HAS_COPY_DISPOSE: block_flags = 1 << 25;
 /// compiler: helpers have C++ code
 pub const BLOCK_HAS_CTOR: block_flags = 1 << 26;
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 /// compiler
 pub const BLOCK_IS_GC: block_flags = 1 << 27;
 
@@ -124,7 +126,7 @@ pub const BLOCK_USE_STRET: block_flags = 1 << 29;
 /// compiler
 pub const BLOCK_HAS_SIGNATURE: block_flags = 1 << 30;
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 /// compiler
 pub const BLOCK_HAS_EXTENDED_LAYOUT: block_flags = 1 << 31;
 
@@ -167,7 +169,7 @@ pub const BLOCK_FIELD_IS_WEAK: block_assign_dispose_flags = 16;
 /// called from __block (byref) copy/dispose support routines.
 pub const BLOCK_BYREF_CALLER: block_assign_dispose_flags = 128;
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 pub const BLOCK_ALL_COPY_DISPOSE_FLAGS: block_assign_dispose_flags = BLOCK_FIELD_IS_OBJECT
     | BLOCK_FIELD_IS_BLOCK
     | BLOCK_FIELD_IS_BYREF
@@ -183,6 +185,12 @@ extern "C" {
     pub static _NSConcreteGlobalBlock: Class;
     pub static _NSConcreteStackBlock: Class;
     pub static _NSConcreteMallocBlock: Class;
+    #[cfg(any(doc, feature = "apple", feature = "compiler-rt"))]
+    pub static _NSConcreteAutoBlock: Class;
+    #[cfg(any(doc, feature = "apple", feature = "compiler-rt"))]
+    pub static _NSConcreteFinalizingBlock: Class;
+    #[cfg(any(doc, feature = "apple", feature = "compiler-rt"))]
+    pub static _NSConcreteWeakBlockVariable: Class;
 
     pub fn _Block_copy(block: *const c_void) -> *mut c_void;
     pub fn _Block_release(block: *const c_void);
@@ -198,58 +206,50 @@ extern "C" {
     /// runtime entry point called by the compiler when disposing of objects
     /// inside dispose helper routine
     pub fn _Block_object_dispose(object: *const c_void, flags: block_assign_dispose_flags);
-}
 
-#[cfg(feature = "apple")]
-extern "C" {
+    #[cfg(any(doc, feature = "apple", feature = "compiler-rt"))]
+    pub fn Block_size(block: *mut c_void) -> c_ulong; // usize
+
     // Whether the return value of the block is on the stack.
     // macOS 10.7
+    // #[cfg(any(doc, feature = "apple"))]
     // pub fn _Block_use_stret(block: *mut c_void) -> bool;
 
     // Returns a string describing the block's GC layout.
     // This uses the GC skip/scan encoding.
     // May return NULL.
     // macOS 10.7
+    // #[cfg(any(doc, feature = "apple"))]
     // pub fn _Block_layout(block: *mut c_void) -> *const c_char;
 
     // Returns a string describing the block's layout.
     // This uses the "extended layout" form described above.
     // May return NULL.
     // macOS 10.8
+    // #[cfg(any(doc, feature = "apple"))]
     // pub fn _Block_extended_layout(block: *mut c_void) -> *const c_char;
 
     // Callable only from the ARR weak subsystem while in exclusion zone
     // macOS 10.7
+    // #[cfg(any(doc, feature = "apple"))]
     // pub fn _Block_tryRetain(block: *const c_void) -> bool;
 
     // Callable only from the ARR weak subsystem while in exclusion zone
     // macOS 10.7
+    // #[cfg(any(doc, feature = "apple"))]
     // pub fn _Block_isDeallocating(block: *const c_void) -> bool;
-}
-
-#[cfg(any(feature = "apple", feature = "compiler-rt"))]
-extern "C" {
-    // the raw data space for runtime classes for blocks
-    // class+meta used for stack, malloc, and collectable based blocks
-
-    pub static _NSConcreteAutoBlock: Class;
-    pub static _NSConcreteFinalizingBlock: Class;
-    pub static _NSConcreteWeakBlockVariable: Class;
 
-    pub fn Block_size(block: *mut c_void) -> c_ulong; // usize
-}
-
-#[cfg(any(feature = "apple", feature = "gnustep-1-7"))]
-extern "C" {
     // indicates whether block was compiled with compiler that sets the ABI
     // related metadata bits
     // macOS 10.7
+    // #[cfg(any(doc, feature = "apple", feature = "gnustep-1-7"))]
     // pub fn _Block_has_signature(block: *mut c_void) -> bool;
 
     // Returns a string describing the block's parameter and return types.
     // The encoding scheme is the same as Objective-C @encode.
     // Returns NULL for blocks compiled with some compilers.
     // macOS 10.7
+    // #[cfg(any(doc, feature = "apple", feature = "gnustep-1-7"))]
     // pub fn _Block_signature(block: *mut c_void) -> *const c_char;
 }
 
@@ -340,7 +340,7 @@ pub struct Block_descriptor_with_signature {
     pub encoding: *const c_char,
 }
 
-// #[cfg(feature = "apple")]
+// #[cfg(any(doc, feature = "apple"))]
 // pub layout: *const c_char,
 
 // #[repr(C)]
@@ -400,7 +400,7 @@ pub struct Block_byref {
     pub destroy: Option<unsafe extern "C" fn(src: *mut c_void)>,
 }
 
-#[cfg(feature = "apple")]
+#[cfg(any(doc, feature = "apple"))]
 /// Structure used for on-stack variables that are referenced by blocks.
 ///
 /// requires BLOCK_BYREF_LAYOUT_EXTENDED

objc-sys/CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 * Added `unstable-c-unwind` feature.
+* Use `doc_auto_cfg` to improve documentation output.
 
 
 ## 0.2.0-beta.0 - 2022-06-13

objc-sys/src/class.rs

@@ -1,6 +1,6 @@
 use std::os::raw::{c_char, c_int, c_uint};
 
-#[cfg(not(objfw))]
+#[cfg(any(doc, not(objfw)))]
 use crate::{objc_ivar, objc_method, objc_object, objc_property, objc_property_attribute_t};
 use crate::{objc_protocol, objc_selector, OpaqueData, BOOL, IMP};
 
@@ -13,7 +13,7 @@ pub struct objc_class {
     _p: OpaqueData,
 }
 
-#[cfg(not(objfw))]
+#[cfg(any(doc, not(objfw)))]
 /// This is `c_char` in GNUStep's libobjc2 and `uint8_t` in Apple's objc4.
 ///
 /// The pointer represents opaque data, and is definitely not just an integer,
@@ -25,12 +25,12 @@ type ivar_layout_type = u8;
 
 // May call `resolveClassMethod:` or `resolveInstanceMethod:`.
 extern_c_unwind! {
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_getClassMethod(
         cls: *const objc_class,
         name: *const objc_selector,
     ) -> *const objc_method;
-    #[cfg(not(objfw))] // Available in newer versions
+    #[cfg(any(doc, not(objfw)))] // Available in newer versions
     pub fn class_getInstanceMethod(
         cls: *const objc_class,
         name: *const objc_selector,
@@ -39,10 +39,10 @@ extern_c_unwind! {
     pub fn class_respondsToSelector(cls: *const objc_class, sel: *const objc_selector) -> BOOL;
 
     // #[deprecated = "use class_getMethodImplementation instead"]
-    // #[cfg(apple)]
+    // #[cfg(any(doc, apple))]
     // pub fn class_lookupMethod
     // #[deprecated = "use class_respondsToSelector instead"]
-    // #[cfg(apple)]
+    // #[cfg(any(doc, apple))]
     // pub fn class_respondsToMethod
 }
 
@@ -51,7 +51,7 @@ extern_c! {
     pub fn objc_getClass(name: *const c_char) -> *const objc_class;
     pub fn objc_getRequiredClass(name: *const c_char) -> *const objc_class;
     pub fn objc_lookUpClass(name: *const c_char) -> *const objc_class;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn objc_getMetaClass(name: *const c_char) -> *const objc_class;
     pub fn objc_copyClassList(out_len: *mut c_uint) -> *mut *const objc_class;
     pub fn objc_getClassList(buffer: *mut *const objc_class, buffer_len: c_int) -> c_int;
@@ -61,17 +61,17 @@ extern_c! {
         name: *const c_char,
         extra_bytes: usize,
     ) -> *mut objc_class;
-    #[cfg(apple)]
+    #[cfg(any(doc, apple))]
     pub fn objc_duplicateClass(
         original: *const objc_class,
         name: *const c_char,
         extra_bytes: usize,
     ) -> *mut objc_class;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn objc_disposeClassPair(cls: *mut objc_class);
     pub fn objc_registerClassPair(cls: *mut objc_class);
 
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_addIvar(
         cls: *mut objc_class,
         name: *const c_char,
@@ -85,60 +85,60 @@ extern_c! {
         imp: IMP,
         types: *const c_char,
     ) -> BOOL;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_addProperty(
         cls: *mut objc_class,
         name: *const c_char,
         attributes: *const objc_property_attribute_t,
         attributes_count: c_uint,
     ) -> BOOL;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_addProtocol(cls: *mut objc_class, protocol: *const objc_protocol) -> BOOL;
     pub fn class_conformsToProtocol(cls: *const objc_class, protocol: *const objc_protocol)
         -> BOOL;
 
-    #[cfg(not(objfw))] // Available in newer versions
+    #[cfg(any(doc, not(objfw)))] // Available in newer versions
     pub fn class_copyIvarList(
         cls: *const objc_class,
         out_len: *mut c_uint,
     ) -> *mut *const objc_ivar;
-    #[cfg(not(objfw))] // Available in newer versions
+    #[cfg(any(doc, not(objfw)))] // Available in newer versions
     pub fn class_copyMethodList(
         cls: *const objc_class,
         out_len: *mut c_uint,
     ) -> *mut *const objc_method;
-    #[cfg(not(objfw))] // Available in newer versions
+    #[cfg(any(doc, not(objfw)))] // Available in newer versions
     pub fn class_copyPropertyList(
         cls: *const objc_class,
         out_len: *mut c_uint,
     ) -> *mut *const objc_property;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_copyProtocolList(
         cls: *const objc_class,
         out_len: *mut c_uint,
     ) -> *mut *const objc_protocol;
 
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_createInstance(cls: *const objc_class, extra_bytes: usize) -> *mut objc_object;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_getClassVariable(cls: *const objc_class, name: *const c_char) -> *const objc_ivar;
-    #[cfg(apple)]
+    #[cfg(any(doc, apple))]
     pub fn class_getImageName(cls: *const objc_class) -> *const c_char;
     pub fn class_getInstanceSize(cls: *const objc_class) -> usize;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_getInstanceVariable(
         cls: *const objc_class,
         name: *const c_char,
     ) -> *const objc_ivar;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_getIvarLayout(cls: *const objc_class) -> *const ivar_layout_type;
     pub fn class_getName(cls: *const objc_class) -> *const c_char;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_getProperty(cls: *const objc_class, name: *const c_char) -> *const objc_property;
     pub fn class_getSuperclass(cls: *const objc_class) -> *const objc_class;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_getVersion(cls: *const objc_class) -> c_int;
-    #[cfg(apple)]
+    #[cfg(any(doc, apple))]
     pub fn class_getWeakIvarLayout(cls: *const objc_class) -> *const ivar_layout_type;
     pub fn class_isMetaClass(cls: *const objc_class) -> BOOL;
     pub fn class_replaceMethod(
@@ -147,18 +147,18 @@ extern_c! {
         imp: IMP,
         types: *const c_char,
     ) -> IMP;
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_replaceProperty(
         cls: *mut objc_class,
         name: *const c_char,
         attributes: *const objc_property_attribute_t,
         attributes_len: c_uint,
     );
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_setIvarLayout(cls: *mut objc_class, layout: *const ivar_layout_type);
-    #[cfg(not(objfw))]
+    #[cfg(any(doc, not(objfw)))]
     pub fn class_setVersion(cls: *mut objc_class, version: c_int);
-    #[cfg(apple)]
+    #[cfg(any(doc, apple))]
     pub fn class_setWeakIvarLayout(cls: *mut objc_class, layout: *const ivar_layout_type);
 
     // #[deprecated = "not recommended"]

objc-sys/src/constants.rs

@@ -1,6 +1,6 @@
 //! Various common #defines and enum constants.
 
-#[cfg(apple)]
+#[cfg(any(doc, apple))]
 use std::os::raw::c_int;
 
 use crate::{id, objc_class, BOOL};
@@ -26,13 +26,13 @@ pub const OBJC_ASSOCIATION_COPY_NONATOMIC: objc_AssociationPolicy = 3;
 pub const OBJC_ASSOCIATION_RETAIN: objc_AssociationPolicy = 769;
 pub const OBJC_ASSOCIATION_COPY: objc_AssociationPolicy = 771;
 
-#[cfg(apple)]
+#[cfg(any(doc, apple))]
 pub const OBJC_SYNC_SUCCESS: c_int = 0;
-#[cfg(apple)]
+#[cfg(any(doc, apple))]
 pub const OBJC_SYNC_NOT_OWNING_THREAD_ERROR: c_int = -1;
 /// Only relevant before macOS 10.13
-#[cfg(apple)]
+#[cfg(any(doc, apple))]
 pub const OBJC_SYNC_TIMED_OUT: c_int = -2;
 /// Only relevant before macOS 10.13
-#[cfg(apple)]
+#[cfg(any(doc, apple))]
 pub const OBJC_SYNC_NOT_INITIALIZED: c_int = -3;