From d706fff45ea010bbcc8ffb604958d46228773a32 Mon Sep 17 00:00:00 2001 From: JamesWrigley Date: Wed, 15 May 2024 15:28:06 +0200 Subject: [PATCH] Clean up reference docs This properly fixes the issue with inner constructor docstrings not being displayed in the docs. Previously they were copied into the main `Socket`/`Message` type docstrings, but with `@doc` they're now recognized. Also added compat warnings for deprecated socket types. --- docs/src/reference.md | 10 +++++++ src/constants.jl | 31 ++++++++++++++++++--- src/message.jl | 64 +++++-------------------------------------- src/socket.jl | 20 ++------------ 4 files changed, 46 insertions(+), 79 deletions(-) diff --git a/docs/src/reference.md b/docs/src/reference.md index 628f327..a654da5 100644 --- a/docs/src/reference.md +++ b/docs/src/reference.md @@ -6,6 +6,9 @@ The ZMQ Socket type: ```@docs Socket +Socket(::Context, ::Integer) +Socket(::Integer) +Socket(::Function) isopen close ``` @@ -42,6 +45,13 @@ DOWNSTREAM ```@docs Message +Message() +Message(::Integer) +Message(::Any) +Message(::String) +Message(::SubString{String}) +Message(::Array) +Message(::IOBuffer) ``` ## Context diff --git a/src/constants.jl b/src/constants.jl index 7e0f96e..324b004 100644 --- a/src/constants.jl +++ b/src/constants.jl @@ -28,13 +28,36 @@ const PUSH = 8 const XPUB = 9 "[XSUB](https://zeromq.org/socket-api/#xsub-socket) socket." const XSUB = 10 -"[XREQ](https://zeromq.org/socket-api/#dealer-socket) socket." +""" +[XREQ](https://zeromq.org/socket-api/#dealer-socket) socket. + +!!! compat + This is a deprecated alias for [ZMQ.DEALER](@ref). +""" const XREQ = DEALER -"[XREP](https://zeromq.org/socket-api/#router-socket) socket." + +""" +[XREP](https://zeromq.org/socket-api/#router-socket) socket. + +!!! compat + This is a deprecated alias for [ZMQ.ROUTER](@ref). +""" const XREP = ROUTER -"[UPSTREAM](https://zeromq.org/socket-api/#pull-socket) socket." + +""" +[UPSTREAM](https://zeromq.org/socket-api/#pull-socket) socket. + +!!! compat + This is a deprecated alias for [ZMQ.PULL](@ref). +""" const UPSTREAM = PULL -"[DOWNSTREAM](https://zeromq.org/socket-api/#push-socket) socket." + +""" +[DOWNSTREAM](https://zeromq.org/socket-api/#push-socket) socket. + +!!! compat + This is a deprecated alias for [ZMQ.PUSH](@ref). +""" const DOWNSTREAM = PUSH #Message options diff --git a/src/message.jl b/src/message.jl index 646dda3..c6f4060 100644 --- a/src/message.jl +++ b/src/message.jl @@ -24,63 +24,13 @@ end """ High-level Message object for sending/receiving ZMQ messages in shared buffers. - - Message() - -Create an empty message (for receive). - ---- - - Message(len::Integer) - -Create a message with a given buffer size (for send). - ---- - - Message(origin::Any, m::Ptr{T}, len::Integer) where {T} - -Low-level function to create a message (for send) with an existing -data buffer, without making a copy. The origin parameter should -be the Julia object that is the origin of the data, so that -we can hold a reference to it until ZMQ is done with the buffer. - ---- - - Message(m::String) - -Create a message with a string as a buffer (for send). Note: the Message now -"owns" the string, it must not be resized, or even written to after the message -is sent. - ---- - - Message(p::SubString{String}) - -Create a message with a sub-string as a buffer (for send). Note: the same -ownership semantics as for [`Message(m::String)`](@ref) apply. - ---- - - Message(a::Array) - -Create a message with an array as a buffer (for send). Note: the same -ownership semantics as for [`Message(m::String)`](@ref) apply. - ---- - - Message(io::IOBuffer) - -Create a message with an -[`IOBuffer`](https://docs.julialang.org/en/v1/base/io-network/#Base.IOBuffer) as -a buffer (for send). Note: the same ownership semantics as for -[`Message(m::String)`](@ref) apply. """ mutable struct Message <: AbstractArray{UInt8,1} # Matching the declaration in the header: char _[64]; w_padding::_Message handle::Ptr{Cvoid} # index into gc_protect, if any - """ + @doc """ Message() Create an empty message (for receive). @@ -96,7 +46,7 @@ mutable struct Message <: AbstractArray{UInt8,1} return zmsg end - """ + @doc """ Message(len::Integer) Create a message with a given buffer size (for send). @@ -112,7 +62,7 @@ mutable struct Message <: AbstractArray{UInt8,1} return zmsg end - """ + @doc """ Message(origin::Any, m::Ptr{T}, len::Integer) where {T} Low-level function to create a message (for send) with an existing @@ -134,7 +84,7 @@ mutable struct Message <: AbstractArray{UInt8,1} return zmsg end - """ + @doc """ Message(m::String) Create a message with a string as a buffer (for send). Note: the Message now @@ -143,7 +93,7 @@ mutable struct Message <: AbstractArray{UInt8,1} """ Message(m::String) = Message(m, pointer(m), sizeof(m)) - """ + @doc """ Message(p::SubString{String}) Create a message with a sub-string as a buffer (for send). Note: the same @@ -152,7 +102,7 @@ mutable struct Message <: AbstractArray{UInt8,1} Message(p::SubString{String}) = Message(p, pointer(p.string)+p.offset, sizeof(p)) - """ + @doc """ Message(a::Array) Create a message with an array as a buffer (for send). Note: the same @@ -160,7 +110,7 @@ mutable struct Message <: AbstractArray{UInt8,1} """ Message(a::Array) = Message(a, pointer(a), sizeof(a)) - """ + @doc """ Message(io::IOBuffer) Create a message with an diff --git a/src/socket.jl b/src/socket.jl index 4680b16..ee884b2 100644 --- a/src/socket.jl +++ b/src/socket.jl @@ -1,27 +1,11 @@ """ A ZMQ socket. - - Socket(typ::Integer) - -Create a socket of a certain type. - ---- - - Socket(ctx::Context, typ::Integer) - -Create a socket in a given context. - ---- - - Socket(f::Function, args...) - -Do-block constructor. """ mutable struct Socket data::Ptr{Cvoid} pollfd::FDWatcher - """ + @doc """ Socket(ctx::Context, typ::Integer) Create a socket in a given context. @@ -38,7 +22,7 @@ mutable struct Socket return socket end - """ + @doc """ Socket(typ::Integer) Create a socket of a certain type.