From 7dad3ee6e962c2fb8fc4e96a9fb06c4cd7fdae33 Mon Sep 17 00:00:00 2001 From: Jakob Nybo Nissen Date: Mon, 27 Nov 2023 07:01:45 +0100 Subject: [PATCH] Document Base.StatStruct's fields as public (#50177) These fields are documented in the docstring of `stat`, and also mentioned as being public in the style guide, but their types are not documented, nor is `StatStruct` directly documented. --------- Co-authored-by: Jameson Nash --- base/stat.jl | 55 +++++++++++++++++++++++++++++++++++++--------------- test/file.jl | 22 +++++++++++++++++++++ 2 files changed, 61 insertions(+), 16 deletions(-) diff --git a/base/stat.jl b/base/stat.jl index 43c51b0b911df..56b960c4f74ea 100644 --- a/base/stat.jl +++ b/base/stat.jl @@ -25,6 +25,30 @@ export stat, uperm +""" + StatStruct + +A struct which stores the information from `stat`. +The following fields of this struct is considered public API: + +| Name | Type | Description | +|:--------|:--------------------------------|:-------------------------------------------------------------------| +| desc | `Union{String, Base.OS_HANDLE}` | The path or OS file descriptor | +| size | `Int64` | The size (in bytes) of the file | +| device | `UInt` | ID of the device that contains the file | +| inode | `UInt` | The inode number of the file | +| mode | `UInt` | The protection mode of the file | +| nlink | `Int` | The number of hard links to the file | +| uid | `UInt` | The user id of the owner of the file | +| gid | `UInt` | The group id of the file owner | +| rdev | `UInt` | If this file refers to a device, the ID of the device it refers to | +| blksize | `Int64` | The file-system preferred block size for the file | +| blocks | `Int64` | The number of 512-byte blocks allocated | +| mtime | `Float64` | Unix timestamp of when the file was last modified | +| ctime | `Float64` | Unix timestamp of when the file's metadata was changed | + +See also: [`stat`](@ref) +""" struct StatStruct desc :: Union{String, OS_HANDLE} # for show method, not included in equality or hash device :: UInt @@ -173,22 +197,21 @@ stat(fd::Integer) = stat(RawFD(fd)) Return a structure whose fields contain information about the file. The fields of the structure are: -| Name | Description | -|:--------|:-------------------------------------------------------------------| -| desc | The path or OS file descriptor | -| size | The size (in bytes) of the file | -| device | ID of the device that contains the file | -| inode | The inode number of the file | -| mode | The protection mode of the file | -| nlink | The number of hard links to the file | -| uid | The user id of the owner of the file | -| gid | The group id of the file owner | -| rdev | If this file refers to a device, the ID of the device it refers to | -| blksize | The file-system preferred block size for the file | -| blocks | The number of 512-byte blocks allocated | -| mtime | Unix timestamp of when the file was last modified | -| ctime | Unix timestamp of when the file's metadata was changed | - +| Name | Type | Description | +|:--------|:--------------------------------|:-------------------------------------------------------------------| +| desc | `Union{String, Base.OS_HANDLE}` | The path or OS file descriptor | +| size | `Int64` | The size (in bytes) of the file | +| device | `UInt` | ID of the device that contains the file | +| inode | `UInt` | The inode number of the file | +| mode | `UInt` | The protection mode of the file | +| nlink | `Int` | The number of hard links to the file | +| uid | `UInt` | The user id of the owner of the file | +| gid | `UInt` | The group id of the file owner | +| rdev | `UInt` | If this file refers to a device, the ID of the device it refers to | +| blksize | `Int64` | The file-system preferred block size for the file | +| blocks | `Int64` | The number of 512-byte blocks allocated | +| mtime | `Float64` | Unix timestamp of when the file was last modified | +| ctime | `Float64` | Unix timestamp of when the file's metadata was changed | """ stat(path...) = stat(joinpath(path...)) diff --git a/test/file.jl b/test/file.jl index b392ffb3e8161..808fba52f9048 100644 --- a/test/file.jl +++ b/test/file.jl @@ -1695,6 +1695,28 @@ if Sys.iswindows() end end +# Unusually for structs, we test this explicitly because the fields of StatStruct +# is part of its documentation, and therefore cannot change. +@testset "StatStruct has promised fields" begin + f, io = mktemp() + s = stat(f) + @test s isa Base.StatStruct + + @test s.desc isa Union{String, Base.OS_HANDLE} + @test s.size isa Int64 + @test s.device isa UInt + @test s.inode isa UInt + @test s.mode isa UInt + @test s.nlink isa Int + @test s.uid isa UInt + @test s.gid isa UInt + @test s.rdev isa UInt + @test s.blksize isa Int64 + @test s.blocks isa Int64 + @test s.mtime isa Float64 + @test s.ctime isa Float64 +end + @testset "StatStruct show's extended details" begin f, io = mktemp() s = stat(f)