allow documentation callbacks

.github/workflows/ci.yml

@@ -24,33 +24,24 @@ jobs:
           - os: macOS-latest
             arch: x86
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@latest
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v1
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts
-          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-test-${{ env.cache-name }}-
-            ${{ runner.os }}-test-
-            ${{ runner.os }}-
-      - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-runtest@v1
-      - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v1
+      - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-buildpkg@latest
+      - uses: julia-actions/julia-runtest@latest
+      - uses: julia-actions/julia-processcoverage@latest
+      - uses: codecov/codecov-action@v3
         with:
           file: lcov.info
   docs:
     name: Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: julia-actions/setup-julia@v1
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@latest
         with:
           version: '1.8'
       - run: |

src/generator/documentation.jl

@@ -1,11 +1,6 @@
-
-function print_documentation(io::IO, node::ExprNode, indent, options, members::Bool=false; kwargs...)
-    print_documentation(io, node.cursor, indent, options, members; kwargs...)
-end
-
 const ESCAPE_PATTERN = r"""(\$|\\|"(?=""))"""
 
-function print_documentation(io::IO, cursor::CLCursor, indent, options, members::Bool=false; 
+function print_documentation(io::IO, node::ExprNode, indent, options, members::Bool=false; 
         prologue::Vector{String}=String[], epilogue::Vector{String}=String[])
 
     fold_single_line_comment = get(options, "fold_single_line_comment", false)
@@ -14,15 +9,19 @@ function print_documentation(io::IO, cursor::CLCursor, indent, options, members:
     ids = get(options, "DAG_ids", Dict())
 
     if extract_c_comment_style == "doxygen"
-        doc = format_doxygen(cursor, options, members)
+        doc = format_doxygen(node.cursor, options, members)
     elseif extract_c_comment_style == "raw"
-        doc = format_raw(cursor, members)
+        doc = format_raw(node.cursor, members)
     else
-        return
+        if (callback_documentation = get(options, "callback_documentation", nothing)) ≢ nothing
+            doc = callback_documentation(node)
+        else
+            return
+        end
     end
 
-    if show_c_function_prototype && cursor isa Clang.CLFunctionDecl
-        prototype = ["### Prototype", "```c", get_prototype(cursor), "```"]
+    if show_c_function_prototype && node.cursor isa Clang.CLFunctionDecl
+        prototype = ["### Prototype", "```c", get_prototype(node), "```"]
     else
         prototype = String[]
     end

test/Project.toml

@@ -3,6 +3,7 @@ BinaryBuilder = "12aac903-9f7c-5d81-afc2-d9565ea332ae"
 CEnum = "fa961155-64e5-5f13-b03f-caf6b980ea82"
 CMake = "631607c0-34d2-5d66-819e-eb0f9aa2061a"
 Libdl = "8f399da3-3557-5675-b5ff-fb832c97cbdb"
+Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 Tar = "a4e569a6-e804-4fa4-b0f3-eef7a1d5b13e"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 p7zip_jll = "3f19e933-33d8-53b3-aaab-bd5110c3b7a0"

test/mpi/generator.toml

@@ -0,0 +1,5 @@
+[general]
+library_name = "libmpi"
+output_common_file_path = "./build/mpi_common.jl"
+output_api_file_path = "./build/mpi_api.jl"
+output_ignorelist = ["^PMPI_"]

test/mpi/mpi.h

@@ -0,0 +1,3 @@
+typedef int MPI_Comm;
+int MPI_Barrier(MPI_Comm comm);
+int PMPI_Barrier(MPI_Comm comm);

test/runtests.jl

@@ -1,5 +1,9 @@
 using Clang
 using Test
+using Pkg
 
 include("generators.jl")
+
+include("test_mpi.jl")
+Pkg.build("CMake")
 include("test_bitfield.jl")

test/test_mpi.jl

@@ -0,0 +1,20 @@
+using Clang.Generators
+
+@testset "MPI.jl" begin
+    @info "Testing generator for JuliaParallel/MPI.jl"
+    args = get_default_args()
+    headers = joinpath(@__DIR__, "mpi", "mpi.h")
+    options = load_options(joinpath(@__DIR__, "mpi", "generator.toml"))
+    options["general"]["callback_documentation"] = node -> String["Fancy MPI doc for $(node.id) generated by Clang.jl"]
+    ctx = create_context(headers, args, options)
+    build!(ctx)
+
+    @info "Testing correctness of the generated files"
+    content = read("build/mpi_api.jl", String)
+
+    # excluded by pattern in `output_ignorelist` of `generator.toml`
+    @test !occursin("PMPI_Barrier", content)
+
+    # custom documentaton callback
+    @test occursin("Fancy MPI doc for MPI_Barrier generated by Clang.jl", content)
+end