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

@@ -6,6 +6,9 @@ The ZMQ Socket type:
 
 ```@docs
 Socket
+Socket(::Context, ::Integer)
+Socket(::Integer)
+Socket(::Function)
 isopen
 close
 ```
@@ -42,6 +45,12 @@ DOWNSTREAM
 
 ```@docs
 Message
+Message()
+Message(::Integer)
+Message(::Any)
+Message(::String)
+Message(::Array)
+Message(::IOBuffer)
 ```
 
 ## Context

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

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,15 +102,15 @@ 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
     ownership semantics as for [`Message(m::String)`](@ref) apply.
     """
     Message(a::Array) = Message(a, pointer(a), sizeof(a))
 
-    """
+    @doc """
         Message(io::IOBuffer)
 
     Create a message with an

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.