Skip to content

Commit

Permalink
Document Base.StatStruct's fields as public (JuliaLang#50177)
Browse files Browse the repository at this point in the history 
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 <vtjnash@gmail.com>
  • Loading branch information
@jakobnissen @vtjnash @mkitti
2 people authored and mkitti committed Dec 9, 2023
1 parent 1e167ce commit 7dad3ee
Show file tree
Hide file tree
Showing 2 changed files with 61 additions and 16 deletions.
55 changes: 39 additions & 16 deletions base/stat.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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...))

Expand Down
22 changes: 22 additions & 0 deletions test/file.jl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down

0 comments on commit 7dad3ee

Please sign in to comment.