fixup! Generate bindings for zmq.h using Clang.jl

docs/make.jl

@@ -11,6 +11,7 @@ makedocs(
             "man/examples.md",
         ],
         "Reference" => "reference.md",
+        "Bindings" => "bindings.md"
     ],
     format = Documenter.HTML(prettyurls = get(ENV, "CI", nothing) == "true")
 )

docs/src/bindings.md

@@ -0,0 +1,15 @@
+# Bindings
+
+This page documents the low-level bindings to libzmq that were automatically
+generated. Where possible, the docstrings link to the [upstream
+documentation](https://libzmq.readthedocs.io). Bindings have not been generated
+for deprecated functions.
+
+!!! danger
+    These bindings are unsafe, do not use them unless you know what you're doing.
+
+---
+
+```@autodocs
+Modules = [ZMQ.lib]
+```

docs/src/index.md

@@ -10,6 +10,6 @@
 
 The [Guide](@ref) provides a tutorial explaining how to get started using ZMQ.jl.
 
-Some examples of packages using Documenter can be found on the [Examples](@ref) page.
+Some examples are linked on the [Examples](@ref) page.
 
-See the [Reference](@ref) for the complete list of documented functions and types.
+See the [Reference](@ref) for the complete list of wrapped functions and types.

gen/gen.jl

@@ -1,4 +1,5 @@
 import Clang
+import Clang.Generators: FunctionProto
 import ZeroMQ_jll
 import MacroTools: @capture, postwalk, prettify
 
@@ -51,9 +52,37 @@ function get_msg_methods(ctx, module_name)
     return methods
 end
 
+# See:
+# https://github.com/zeromq/libzmq/blob/c2fae81460d9d39a896da7b3f72484d23a172fa7/include/zmq.h#L582-L611
+const undocumented_functions = [:zmq_stopwatch_start,
+                                :zmq_stopwatch_intermediate,
+                                :zmq_stopwatch_stop,
+                                :zmq_sleep,
+                                :zmq_threadstart,
+                                :zmq_threadclose]
+function get_docs(node, doc)
+    # Only add docstrings for functions
+    if !(node.type isa FunctionProto)
+        return doc
+    end
+
+    url_prefix = "https://libzmq.readthedocs.io/en/latest"
+
+    # The timer functions are all documented on a single page
+    if startswith(string(node.id), "zmq_timers")
+        return ["[Upstream documentation]($(url_prefix)/zmq_timers.html)."]
+    elseif node.id in undocumented_functions
+        return ["This is an undocumented function, not part of the formal ZMQ API."]
+    else
+        # For all the others, generate the URL from the function name
+        return ["[Upstream documentation]($(url_prefix)/$(node.id).html)."]
+    end
+end
+
 cd(@__DIR__) do
     # Set the options
     options = Clang.load_options(joinpath(@__DIR__, "generator.toml"))
+    options["general"]["callback_documentation"] = get_docs
     header = joinpath(ZeroMQ_jll.artifact_dir, "include", "zmq.h")
     args = Clang.get_default_args()
 

gen/generator.toml

@@ -3,7 +3,11 @@ library_name = "libzmq"
 module_name = "lib"
 output_file_path = "../src/bindings.jl"
 print_using_CEnum = false
-output_ignorelist = ["ZMQ_VERSION"]
+output_ignorelist = ["ZMQ_VERSION", # This macro cannot be parsed by Clang.jl
+                     # These functions/types are deprecated
+                     "zmq_init", "zmq_term", "zmq_ctx_destroy",
+                     "zmq_device", "zmq_sendmsg", "zmq_recvmsg",
+                     "iovec", "zmq_sendiov", "zmq_recviov"]
 prologue_file_path = "./prologue.jl"
 
 auto_mutability = true