From 26c84f27fbea48c3f47f96d33566c58613f6732a Mon Sep 17 00:00:00 2001
From: Christian Guinard <28689358+christiangnrd@users.noreply.github.com>
Date: Thu, 18 Jul 2024 11:06:06 -0300
Subject: [PATCH] Move versions.jl to `Metal` module.

Add docstrings
---
 docs/src/api/essentials.md  |  8 ++++++++
 lib/mtl/MTL.jl              |  3 ++-
 src/Metal.jl                |  2 ++
 {lib/mtl => src}/version.jl | 40 +++++++++++++++++++++++++++++++++----
 test/execution.jl           |  3 +--
 5 files changed, 49 insertions(+), 7 deletions(-)
 rename {lib/mtl => src}/version.jl (77%)

diff --git a/docs/src/api/essentials.md b/docs/src/api/essentials.md
index d1fc0da6f..0536da2d3 100644
--- a/docs/src/api/essentials.md
+++ b/docs/src/api/essentials.md
@@ -1,5 +1,13 @@
 # Essentials
 
+## Versions and Support
+```@docs
+macos_version
+Metal.darwin_version
+Metal.metal_support
+Metal.metallib_support
+Metal.air_support
+```
 
 ## Global State
 
diff --git a/lib/mtl/MTL.jl b/lib/mtl/MTL.jl
index 125d096e2..e8d77898c 100644
--- a/lib/mtl/MTL.jl
+++ b/lib/mtl/MTL.jl
@@ -11,6 +11,8 @@ module MTL
 using CEnum
 using ObjectiveC, .Foundation, .Dispatch
 
+using ..Metal
+
 # Metal APIs generally expect to be running under an autorelease pool.
 # In most cases, we handle this in the code calling into the MTL module,
 # however, finalizers are out of the caller's control, so we need to
@@ -20,7 +22,6 @@ release(obj) = @autoreleasepool unsafe=true Foundation.release(obj)
 
 ## source code includes
 
-include("version.jl")
 include("size.jl")
 include("device.jl")
 include("resource.jl")
diff --git a/src/Metal.jl b/src/Metal.jl
index a44f5f63a..c8af0d2b2 100644
--- a/src/Metal.jl
+++ b/src/Metal.jl
@@ -14,6 +14,8 @@ using ExprTools: splitdef, combinedef
 using Artifacts
 using ObjectiveC, .CoreFoundation, .Foundation, .Dispatch, .OS
 
+include("version.jl")
+
 # core library
 include("../lib/mtl/MTL.jl")
 using .MTL
diff --git a/lib/mtl/version.jl b/src/version.jl
similarity index 77%
rename from lib/mtl/version.jl
rename to src/version.jl
index f95562db0..89db5876a 100644
--- a/lib/mtl/version.jl
+++ b/src/version.jl
@@ -1,6 +1,6 @@
 # version and support queries
 
-export darwin_version, macos_version, metallib_support, air_support, metal_support
+export macos_version
 
 @noinline function _syscall_version(name)
     size = Ref{Csize_t}()
@@ -18,6 +18,13 @@ export darwin_version, macos_version, metallib_support, air_support, metal_suppo
 end
 
 const _darwin_version = Ref{VersionNumber}()
+"""
+    Metal.darwin_version() -> VersionNumber
+
+Returns the host Darwin kernel version.
+
+See also [`macos_version`](@ref).
+"""
 function darwin_version()
     if !isassigned(_darwin_version)
         _darwin_version[] = _syscall_version("kern.osrelease")
@@ -26,6 +33,13 @@ function darwin_version()
 end
 
 const _macos_version = Ref{VersionNumber}()
+"""
+    macos_version() -> VersionNumber
+
+Returns the host macOS version.
+
+See also [`Metal.darwin_version`](@ref).
+"""
 function macos_version()
     if !isassigned(_macos_version)
         _macos_version[] = _syscall_version("kern.osproductversion")
@@ -46,7 +60,13 @@ end
 # - metal support: last 2 bytes of the VERS tag in the function list,
 #                  or air.language_version in the embedded bitcode
 
-# support for the metallib file format
+"""
+    Metal.metallib_support() -> VersionNumber
+
+Returns the highest supported version for the metallib file format.
+
+See also [`Metal.air_support`](@ref) and [`Metal.metal_support`](@ref).
+"""
 function metallib_support()
     macos = macos_version()
     if macos >= v"15"
@@ -68,7 +88,13 @@ function metallib_support()
     end
 end
 
-# support for the embedded AIR bitcode format
+"""
+    Metal.air_support() -> VersionNumber
+
+Returns the highest supported version for the embedded AIR bitcode format.
+
+See also [`Metal.metallib_support`](@ref) and [`Metal.metal_support`](@ref).
+"""
 function air_support()
     macos = macos_version()
     if macos >= v"15"
@@ -92,7 +118,13 @@ function air_support()
     end
 end
 
-# support for the Metal language
+"""
+    Metal.metal_support() -> VersionNumber
+
+Returns the highest supported version for the Metal Shading Language.
+
+See also [`Metal.metallib_support`](@ref) and [`Metal.air_support`](@ref).
+"""
 function metal_support()
     macos = macos_version()
     if macos >= v"15"
diff --git a/test/execution.jl b/test/execution.jl
index 9937a343a..d0bd2f2c9 100644
--- a/test/execution.jl
+++ b/test/execution.jl
@@ -1,4 +1,3 @@
-using Metal: macos_version, MTLCommandQueue
 
 dummy() = return
 
@@ -143,7 +142,7 @@ end
     vecA .= 0
 
     dev = device()
-    queue = MTLCommandQueue(dev)
+    queue = MTL.MTLCommandQueue(dev)
     @metal threads=(3) queue=queue tester(bufferA)
     synchronize(queue)
     @test all(vecA == Int.([5, 5, 5, 0, 0, 0, 0, 0]))