# Base.@ccallable blows chunks

**URL:** <https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572>\
**Category:** General Usage\
**Tags:** package-compiler\
**Created:** [October 4, 2023, 1:33pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572 "2023-10-04T13:33:30Z")\
**Posts on this page:** 10\
**Page:** 1

<div class="post-metadata">

**Author:** ![Allan\_Baker](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/allan_baker/32/42645_2.png) [@Allan\_Baker](https://discourse.julialang.org/u/Allan_Baker)\
**Post date:** [October 4, 2023, 1:33pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/1 "2023-10-04T13:33:30Z")

</div>

Not much documentation out there I have found to help me with this. Do we not allow setting of references in the @ccallable function? I’ve had this problem with every function I tried to define as @ccallable for use in a C-library with PackageCompiler. This is my first time attempting to use PacakgeCompiler.

The code:

```julia
const inputRef=Ref{julia_input_data}(julia_input_data())
const isCalculationValid=Ref{Bool}(false)

Base.@ccallable function julia_reset_inputRef()::Cint
    inputRef[]=julia_input_data()
    isCalculationValid[]=false
    return Cint(0)
end

```

The output (sanitized)

```julia
ERROR: LoadError: cannot document the following expression:
#= c:\mydir\mypackage\src\mypac_ccall_interface.jl:87 =# 
Base.@ccallable function julia_reset_inputRef()::Cint
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:87 =#
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:88 =#
        inputRef[] = julia_input_data()
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:89 =#
        isCalculationValid[] = false
        #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:90 =#
        return Cint(0)
    end

'Base.var"@ccallable"' not documentable. See 'Bas

```

---

<div class="post-metadata">

**Author:** ![Benny](https://avatars.discourse-cdn.com/v4/letter/b/49beb7/32.png) [@Benny](https://discourse.julialang.org/u/Benny)\
**Post date:** [October 4, 2023, 2:10pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/2 "2023-10-04T14:10:42Z")

</div>

That error usually shows up when you try to attach a docstring to a macro call that returns a compound expression but lacks `Base.@ __doc__ ` marking which subexpressions the docstring is attached to, [see here](https://docs.julialang.org/en/v1/manual/documentation/#Macro-generated-code). If you `@macroexpand` the `@ccallable` expression you can see it’s a compound expression. It’s strange because your code doesn’t have docstrings at all.

---

<div class="post-metadata">

**Author:** ![Allan\_Baker](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/allan_baker/32/42645_2.png) [@Allan\_Baker](https://discourse.julialang.org/u/Allan_Baker)\
**Post date:** [October 4, 2023, 2:26pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/3 "2023-10-04T14:26:18Z")

</div>

That’s because I didn’t give you that part. 🙂

```julia
"The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
function julia_reset_inputRef()::Cint
    inputRef[]=julia_input_data()
    isCalculationValid[]=false
    return Cint(0)
end

```

So you are saying that I can’t have a docstring attached to any function that uses Base.@ccallable?

---

<div class="post-metadata">

**Author:** ![Allan\_Baker](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/allan_baker/32/42645_2.png) [@Allan\_Baker](https://discourse.julialang.org/u/Allan_Baker)\
**Post date:** [October 4, 2023, 2:30pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/4 "2023-10-04T14:30:56Z")

</div>

I think you may be a genius. Any way to properly document C-library designated functions?

---

<div class="post-metadata">

**Author:** ![mbauman](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mbauman/32/31082_2.png) [@mbauman](https://discourse.julialang.org/u/mbauman)\
**Post date:** [October 4, 2023, 2:38pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/5 "2023-10-04T14:38:00Z")

</div>

Honestly, that sounds like a bug with the docs system. [Could you file an issue](https://github.com/JuliaLang/julia/issues/new/)?

---

<div class="post-metadata">

**Author:** ![mkitti](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mkitti/32/12459_2.png) [@mkitti](https://discourse.julialang.org/u/mkitti)\
**Post date:** [October 4, 2023, 2:44pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/6 "2023-10-04T14:44:17Z")

</div>

> [@Allan\_Baker](#):
>
> ```julia
> "The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
> function julia_reset_inputRef()
> 
> ```

How about assigning the docstring to a free function.

```julia
"The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
julia_reset_inputRef

Base.@ccallable function julia_reset_inputRef()::Cint
   # ...
end

```

---

<div class="post-metadata">

**Author:** ![Allan\_Baker](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/allan_baker/32/42645_2.png) [@Allan\_Baker](https://discourse.julialang.org/u/Allan_Baker)\
**Post date:** [October 4, 2023, 2:54pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/7 "2023-10-04T14:54:32Z")

</div>

If I can remember my github account login I will. 🙂

---

<div class="post-metadata">

**Author:** ![Allan\_Baker](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/allan_baker/32/42645_2.png) [@Allan\_Baker](https://discourse.julialang.org/u/Allan_Baker)\
**Post date:** [October 4, 2023, 3:02pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/8 "2023-10-04T15:02:01Z")

</div>

> [@Allan\_Baker](#):
>
> ```julia
> ERROR: LoadError: cannot document the following expression:
> #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:87 =# 
> Base.@ccallable function julia_reset_inputRef()::Cint
> #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:87 =#
> #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:88 =#
> inputRef[] = julia_input_data()
> #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:89 =#
> isCalculationValid[] = false
> #= c:\mydir\mypackage\src\mypac_ccall_interface.jl:90 =#
> return Cint(0)
> end
> 
> 'Base.var"@ccallable"' not documentable. See 'Bas
> 
> ```

Done.

> <https://github.com/JuliaLang/julia/issues/51586>
>
> julia\> versioninfo()
> Julia Version 1.9.2
> Commit e4ee485e90 (2023-07-05 09:39 U…TC)
> Platform Info:
> OS: Windows (x86\_64-w64-mingw32)
> CPU: 12 × Intel(R) Core(TM) i7-10850H CPU @ 2.70GHz
> WORD\_SIZE: 64
> LIBM: libopenlibm
> LLVM: libLLVM-14.0.6 (ORCJIT, skylake)
> Threads: 12 on 12 virtual cores
> Environment:
> JULIA\_DIR = C:\\Users\\bakerar\\AppData\\Local\\Programs\\Julia-1.9.2
> JULIA\_PKG\_DEVDIR = D:\\JULIA\\DEVELOPMENT
> JULIA\_PKG\_USE\_CLI\_GIT = true
> JULIA\_EDITOR = code
> JULIA\_NUM\_THREADS =
> 
> https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572?u=allan\_baker
> \`\`\`
> const inputRef=Ref{julia\_input\_data}(julia\_input\_data())
> const isCalculationValid=Ref{Bool}(false)
> 
> "A Docstring here causes an error"
> Base.@ccallable function julia\_reset\_inputRef()::Cint
> inputRef\[\]=julia\_input\_data()
> isCalculationValid\[\]=false
> return Cint(0)
> end
> \`\`\`
> Sanitized Error message:
> \`\`\`ERROR: LoadError: cannot document the following expression:
> \#= c:\\mydir\\mypackage\\src\\mypac\_ccall\_interface.jl:87 =# 
> Base.@ccallable function julia\_reset\_inputRef()::Cint
> #= c:\\mydir\\mypackage\\src\\mypac\_ccall\_interface.jl:87 =#
> #= c:\\mydir\\mypackage\\src\\mypac\_ccall\_interface.jl:88 =#
> inputRef\[\] = julia\_input\_data()
> #= c:\\mydir\\mypackage\\src\\mypac\_ccall\_interface.jl:89 =#
> isCalculationValid\[\] = false
> #= c:\\mydir\\mypackage\\src\\mypac\_ccall\_interface.jl:90 =#
> return Cint(0)
> end
> 
> 'Base.var"@ccallable"' not documentable. See 'Bas
> \`\`\`
> 
> Removing the Docstring fixes the issue.
> 
> EDIT: removed #s since they add annoying issue links

---

<div class="post-metadata">

**Author:** ![mbauman](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mbauman/32/31082_2.png) [@mbauman](https://discourse.julialang.org/u/mbauman)\
**Post date:** [October 4, 2023, 3:12pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/9 "2023-10-04T15:12:16Z")

</div>

Fix proposed in [fix #51586, annotate method from `@ccallable` with `@ __doc__ ` by mbauman · Pull Request #51587 · JuliaLang/julia · GitHub](https://github.com/JuliaLang/julia/pull/51587).

---

<div class="post-metadata">

**Author:** ![Benny](https://avatars.discourse-cdn.com/v4/letter/b/49beb7/32.png) [@Benny](https://discourse.julialang.org/u/Benny)\
**Post date:** [October 4, 2023, 3:18pm UTC](https://discourse.julialang.org/t/base-ccallable-blows-chunks/104572/10 "2023-10-04T15:18:12Z")

</div>

I think this is the only way.

In general there’s no guarantee that you can put a docstring above a macro call transforming an input expression and expect the input expression to be documented; if the output expression is compound, the macro must manually specify which subexpression gets the docstring. If it doesn’t do that, one workaround is to attach the docstring to the input expression in a `begin` block as an input for the macro, hoping the macro is able to handle it. `@ccallable` requires the input to be a `function` block so it can’t. `Base.@ __doc__ ` helps remove the need for macros to tiptoe around or dive into such `begin` blocks.

```julia
julia> Base.@ccallable begin
       "The julia_reset_inputs will disassociate the previous mutable structure reference with the inputRef pointer and create a new julia_input_data object to be referenced."
       function julia_reset_inputRef()::Cint
           inputRef[]=julia_input_data()
           isCalculationValid[]=false
           return Cint(0)
       end
       end
ERROR: LoadError: expected method definition in @ccallable
Stacktrace:
 [1] error(s::String)
   @ Base ./error.jl:35
 [2] expand_ccallable(rt::Nothing, def::Expr)
   @ Base ./c.jl:548
 [3] var"@ccallable"( __source__ ::LineNumberNode, __module__ ::Module, def::Any)
   @ Base ./c.jl:558

```