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

docs/make.jl

@@ -20,6 +20,7 @@ makedocs(
  "man/examples.md",
  ],
  "Reference" => "reference.md",
+ "Bindings" => "bindings.md",
  "Changelog" => "changelog.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