Link to Apple Documentation, explain docs.rs failure

README.md

@@ -2,7 +2,18 @@
 [![Actions Status](https://github.com/gfx-rs/metal-rs/workflows/ci/badge.svg)](https://github.com/gfx-rs/metal-rs/actions)
 [![Crates.io](https://img.shields.io/crates/v/metal.svg?label=metal)](https://crates.io/crates/metal)
 
-Unsafe Rust bindings for the Metal 3D Graphics API.
+<p align="center">
+  <img width="150" height="150" src="./assets/metal.svg">
+</p>
+
+<p align="center">Unsafe Rust bindings for the Metal 3D Graphics API.</p>
+
+## Documentation
+
+Note that [docs.rs](docs.rs) will fail to build the (albiet limited) documentation for this crate!
+They build in a Linux container, but of course this will only compile on MacOS.
+
+Please build the documentation yourself with `cargo docs`.
 
 ## Examples
 

src/argument.rs

@@ -8,6 +8,7 @@
 use super::{MTLTextureType, NSUInteger};
 use objc::runtime::{NO, YES};
 
+/// See <https://developer.apple.com/documentation/metal/mtldatatype>
 #[repr(u64)]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -107,7 +108,9 @@ pub enum MTLDataType {
     RGB9E5Float = 77,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlargumenttype>
 #[repr(u64)]
+#[deprecated(note = "Since: iOS 8.0–16.0, iPadOS 8.0–16.0, macOS 10.11–13.0, Mac Catalyst 13.1–16.0, tvOS 9.0–16.0")]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLArgumentType {
@@ -119,6 +122,7 @@ pub enum MTLArgumentType {
     Imageblock = 17,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlargumentaccess>
 #[repr(u64)]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -128,6 +132,7 @@ pub enum MTLArgumentAccess {
     WriteOnly = 2,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlstructmember>
 pub enum MTLStructMember {}
 
 foreign_obj_type! {
@@ -179,6 +184,7 @@ impl StructMemberArrayRef {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlstructtype>
 pub enum MTLStructType {}
 
 foreign_obj_type! {
@@ -199,6 +205,7 @@ impl StructTypeRef {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlarraytype>
 pub enum MTLArrayType {}
 
 foreign_obj_type! {
@@ -229,6 +236,8 @@ impl ArrayTypeRef {
     }
 }
 
+/// <https://developer.apple.com/documentation/metal/mtlargument>
+#[deprecated(note = "Since iOS 8.0–16.0, iPadOS 8.0–16.0, macOS 10.11–13.0, Mac Catalyst 13.1–16.0, tvOS 9.0–16.0")]
 pub enum MTLArgument {}
 
 foreign_obj_type! {
@@ -300,6 +309,7 @@ impl ArgumentRef {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlargumentdescriptor>
 pub enum MTLArgumentDescriptor {}
 
 foreign_obj_type! {

src/buffer.rs

@@ -7,6 +7,7 @@
 
 use super::*;
 
+/// See <https://developer.apple.com/documentation/metal/mtlbuffer>
 pub enum MTLBuffer {}
 
 foreign_obj_type! {

src/capturedescriptor.rs

@@ -9,7 +9,7 @@ use super::*;
 
 use std::path::Path;
 
-/// https://developer.apple.com/documentation/metal/mtlcapturedestination?language=objc
+/// See <https://developer.apple.com/documentation/metal/mtlcapturedestination?language=objc>
 #[repr(u64)]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -18,7 +18,7 @@ pub enum MTLCaptureDestination {
     GpuTraceDocument = 2,
 }
 
-/// https://developer.apple.com/documentation/metal/mtlcapturedescriptor
+/// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor>
 pub enum MTLCaptureDescriptor {}
 
 foreign_obj_type! {
@@ -37,42 +37,42 @@ impl CaptureDescriptor {
 }
 
 impl CaptureDescriptorRef {
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237248-captureobject
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237248-captureobject>
     pub fn set_capture_device(&self, device: &DeviceRef) {
         unsafe { msg_send![self, setCaptureObject: device] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237248-captureobject
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237248-captureobject>
     pub fn set_capture_scope(&self, scope: &CaptureScopeRef) {
         unsafe { msg_send![self, setCaptureObject: scope] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237248-captureobject
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237248-captureobject>
     pub fn set_capture_command_queue(&self, command_queue: &CommandQueueRef) {
         unsafe { msg_send![self, setCaptureObject: command_queue] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237250-outputurl
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237250-outputurl>
     pub fn output_url(&self) -> &Path {
         let output_url = unsafe { msg_send![self, outputURL] };
         let output_url = nsstring_as_str(output_url);
 
         Path::new(output_url)
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237250-outputurl
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor/3237250-outputurl>
     pub fn set_output_url<P: AsRef<Path>>(&self, output_url: P) {
         let output_url = nsstring_from_str(output_url.as_ref().to_str().unwrap());
 
         unsafe { msg_send![self, setOutputURL: output_url] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor?language=objc
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor?language=objc>
     pub fn destination(&self) -> MTLCaptureDestination {
         unsafe { msg_send![self, destination] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturedescriptor?language=objc
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturedescriptor?language=objc>
     pub fn set_destination(&self, destination: MTLCaptureDestination) {
         unsafe { msg_send![self, setDestination: destination] }
     }

src/capturemanager.rs

@@ -8,6 +8,7 @@
 use super::*;
 use std::ffi::CStr;
 
+/// See <https://developer.apple.com/documentation/metal/mtlcapturescope>
 pub enum MTLCaptureScope {}
 
 foreign_obj_type! {
@@ -33,6 +34,7 @@ impl CaptureScopeRef {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlcapturemanager>
 pub enum MTLCaptureManager {}
 
 foreign_obj_type! {
@@ -70,7 +72,7 @@ impl CaptureManagerRef {
         unsafe { msg_send![self, setDefaultCaptureScope: scope] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturemanager/3237259-startcapture
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturemanager/3237259-startcapture>
     pub fn start_capture(&self, descriptor: &CaptureDescriptorRef) -> Result<(), String> {
         unsafe {
             try_objc! { err =>
@@ -100,7 +102,7 @@ impl CaptureManagerRef {
         unsafe { msg_send![self, isCapturing] }
     }
 
-    /// https://developer.apple.com/documentation/metal/mtlcapturemanager/3237260-supportsdestination?language=objc
+    /// See <https://developer.apple.com/documentation/metal/mtlcapturemanager/3237260-supportsdestination?language=objc>
     pub fn supports_destination(&self, destination: MTLCaptureDestination) -> bool {
         unsafe { msg_send![self, supportsDestination: destination] }
     }

src/commandbuffer.rs

@@ -9,6 +9,7 @@ use super::*;
 
 use block::Block;
 
+/// See <https://developer.apple.com/documentation/metal/mtlcommandbufferstatus>
 #[repr(u32)]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -21,6 +22,7 @@ pub enum MTLCommandBufferStatus {
     Error = 5,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlcommandbuffererror>
 #[repr(u32)]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -37,6 +39,7 @@ pub enum MTLCommandBufferError {
     DeviceRemoved = 11,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtldispatchtype>
 #[repr(u32)]
 #[allow(non_camel_case_types)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
@@ -47,6 +50,7 @@ pub enum MTLDispatchType {
 
 type CommandBufferHandler<'a> = Block<(&'a CommandBufferRef,), ()>;
 
+/// See <https://developer.apple.com/documentation/metal/mtlcommandbuffer>.
 pub enum MTLCommandBuffer {}
 
 foreign_obj_type! {

src/commandqueue.rs

@@ -7,6 +7,7 @@
 
 use super::*;
 
+/// See <https://developer.apple.com/documentation/metal/mtlcommandqueue>.
 pub enum MTLCommandQueue {}
 
 foreign_obj_type! {

src/constants.rs

@@ -5,6 +5,7 @@
 // http://opensource.org/licenses/MIT>, at your option. This file may not be
 // copied, modified, or distributed except according to those terms.
 
+/// See <https://developer.apple.com/documentation/metal/mtlpixelformat>
 #[repr(u64)]
 #[allow(non_camel_case_types)]
 #[derive(Debug, Copy, Clone, Hash, PartialEq, Eq)]

src/depthstencil.rs

@@ -8,6 +8,7 @@
 use crate::DeviceRef;
 use objc::runtime::{NO, YES};
 
+/// See <https://developer.apple.com/documentation/metal/mtlcomparefunction>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLCompareFunction {
@@ -21,6 +22,7 @@ pub enum MTLCompareFunction {
     Always = 7,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlstenciloperation>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLStencilOperation {
@@ -34,6 +36,7 @@ pub enum MTLStencilOperation {
     DecrementWrap = 7,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlstencildescriptor>
 pub enum MTLStencilDescriptor {}
 
 foreign_obj_type! {
@@ -101,6 +104,7 @@ impl StencilDescriptorRef {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtldepthstencildescriptor>
 pub enum MTLDepthStencilDescriptor {}
 
 foreign_obj_type! {
@@ -172,6 +176,7 @@ impl DepthStencilDescriptorRef {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtldepthstencilstate>
 pub enum MTLDepthStencilState {}
 
 foreign_obj_type! {

src/device.rs

@@ -13,8 +13,11 @@ use objc::runtime::{Object, NO, YES};
 
 use std::{ffi::CStr, os::raw::c_char, path::Path, ptr};
 
-// Available on macOS 10.11+, iOS 8.0+, tvOS 9.0+
+/// Available on macOS 10.11+, iOS 8.0+, tvOS 9.0+
+///
+/// See <https://developer.apple.com/documentation/metal/mtlfeatureset>
 #[allow(non_camel_case_types)]
+#[deprecated(note = "Since iOS 8.0–16.0 iPadOS 8.0–16.0 macOS 10.11–13.0 Mac Catalyst 13.1–16.0 tvOS 9.0–16.0")]
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLFeatureSet {
@@ -52,7 +55,9 @@ pub enum MTLFeatureSet {
     macOS_GPUFamily2_v1 = 10005,
 }
 
-// Available on macOS 10.15+, iOS 13.0+
+/// Available on macOS 10.15+, iOS 13.0+
+///
+/// See <https://developer.apple.com/documentation/metal/mtlgpufamily>
 #[repr(i64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 #[non_exhaustive]
@@ -75,6 +80,7 @@ pub enum MTLGPUFamily {
     MacCatalyst2 = 4002,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtldevicelocation>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLDeviceLocation {
@@ -1380,13 +1386,15 @@ impl MTLFeatureSet {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlargumentbufferstier>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLArgumentBuffersTier {
     Tier1 = 0,
     Tier2 = 1,
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlreadwritetexturetier>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLReadWriteTextureTier {
@@ -1396,6 +1404,8 @@ pub enum MTLReadWriteTextureTier {
 }
 
 /// Only available on (macos(11.0), ios(14.0))
+///
+/// See <https://developer.apple.com/documentation/metal/mtlcountersamplingpoint>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLCounterSamplingPoint {
@@ -1407,6 +1417,9 @@ pub enum MTLCounterSamplingPoint {
 }
 
 /// Only available on (macos(11.0), macCatalyst(14.0), ios(13.0))
+/// Kinda a long name!
+///
+/// See <https://developer.apple.com/documentation/metal/mtlsparsetextureregionalignmentmode>
 #[repr(u64)]
 #[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
 pub enum MTLSparseTextureRegionAlignmentMode {
@@ -1431,6 +1444,7 @@ bitflags! {
     }
 }
 
+/// See <https://developer.apple.com/documentation/metal/mtlaccelerationstructuresizes>
 #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
 #[repr(C)]
 pub struct MTLAccelerationStructureSizes {
@@ -1480,6 +1494,7 @@ type MTLNewRenderPipelineStateWithReflectionCompletionHandler = extern fn(render
 type MTLNewComputePipelineStateCompletionHandler = extern fn(computePipelineState: id, error: id);
 type MTLNewComputePipelineStateWithReflectionCompletionHandler = extern fn(computePipelineState: id, reflection: id, error: id);*/
 
+/// See <https://developer.apple.com/documentation/metal/mtldevice>
 pub enum MTLDevice {}
 
 foreign_obj_type! {

src/drawable.rs

@@ -7,6 +7,7 @@
 
 use super::NSUInteger;
 
+/// See <https://developer.apple.com/documentation/metal/mtldrawable>
 pub enum MTLDrawable {}
 
 foreign_obj_type! {