Document Dates.value (#29591)

(cherry picked from commit b7a7002)

Author: amellnik

stdlib/Dates/docs/src/index.md

@@ -511,7 +511,8 @@ it could represent, in days, a value of 28, 29, 30, or 31 depending on the year
 Or a year could represent 365 or 366 days in the case of a leap year. [`Period`](@ref) types are
 simple [`Int64`](@ref) wrappers and are constructed by wrapping any `Int64` convertible type, i.e. `Year(1)`
 or `Month(3.0)`. Arithmetic between [`Period`](@ref) of the same type behave like integers, and
-limited `Period-Real` arithmetic is available.
+limited `Period-Real` arithmetic is available.  You can extract the underlying integer with
+[`Dates.value`](@ref).
 
 ```jldoctest
 julia> y1 = Dates.Year(1)
@@ -537,6 +538,9 @@ julia> y3 % y2
 
 julia> div(y3,3) # mirrors integer division
 3 years
+
+julia> Dates.value(Dates.Millisecond(10))
+10
 ```
 
 ## Rounding
@@ -740,6 +744,7 @@ Dates.toprev(::Function, ::Dates.TimeType)
 ```@docs
 Dates.Period(::Any)
 Dates.CompoundPeriod(::Vector{<:Dates.Period})
+Dates.value
 Dates.default
 ```
 

stdlib/Dates/src/periods.jl

@@ -1,6 +1,12 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
 #Period types
+"""
+    Dates.value(x::Period) -> Int64
+
+For a given period, return the value associated with that period.  For example,
+`value(Millisecond(10))` returns 10 as an integer.
+"""
 value(x::Period) = x.value
 
 # The default constructors for Periods work well in almost all cases