Update calling-c-and-fortran docs

[kmsquire]

This is an updated version of #10799. It's almost entirely formatting and wording updates.

Comments welcome, although I probably won't be able to spend much time on this.

Maintainers should feel free to push edits.

[Gnimuc]

Maybe we can also remove some misleading docs in this PR as per discussed in JuliaInterop/Clang.jl#120 (comment) ?

[Gnimuc]

Note that for this code to work correctly, result_array must be declared to be of type Ref{Cdouble} and not Ptr{Cdouble}. The memory is managed by Julia and the Ref signature alerts Julia's garbage collector to keep managing the memory for result_array while the ccall executes.

I suggest to rephrase or remove the above misleading statements. It just throws some "best practice" rules and doesn't explain the mechanism under the hood.

result_array must be declared to be of type Ref{Cdouble} and not Ptr{Cdouble}.

This is not right. Ptr{Cdouble} should also work safely as long as Base.cconvert(Ptr{Cdouble}, result_array) doesn't violate the mechanism. Currently, it calls Base.cconvert(::Type{<:Ptr}, x) = x where the return value x is guaranteed to be alive (GC-preserved) until the end of ccall.

the Ref signature alerts Julia's garbage collector to keep managing the memory for result_array while the ccall executes.

Again, this is not how it works. Ref is not being treated specially, instead, there are some default cconvert&unsafe_convert methods pre-defined in Julia base, which ensures its GC safety.

BTW, I think we'd better mention more use cases for GC.@preserve in the doc.

[fredrikekre]

Why change this and remove the text below? This is not how it works and gives the wrong impression.

[kmsquire]

The text below is preserved as a footnote. I wrote it this way because I felt that, for most users, cconvert followed by unsafe_convert was more detail than they would want to know, and that this gets the point across (i.e., that the passed values are converted to the appropriate type).

That said, I'm can change it back if you don't think the footnote is enough or appropriate.

[fredrikekre]

I mean, this is the docs for how to ccall so why should I have to scroll to a footnote in order to see how ccall works?

[yuyichao]

for most users, cconvert followed by unsafe_convert was more detail than they would want to know, and that this gets the point across (i.e., that the passed values are converted to the appropriate type).

For any user, they should either not care about anything about conversion for ccall arguments at all, or if they do, they must not related it to convert. This change gets the wrong point across. I've recently seen people still thinking convert is the method to use for this and it's just wrong.

Bottom line is that I don't really mind if this is said in the footnote or not, but you must not mention convert.

[kmsquire]

@Gnimuc I'll try to address your comments today.

BTW, I think we'd better mention more use cases for GC.@preserve in the doc.

I don't have enough grasp of this to add anything useful.
If you'd like to, why don't you either make a PR against my branch here (I'll preserve your commits), or just make a new PR (probably after this is merged).

[kmsquire]

Okay, I've "addressed" @Gnimuc's comments mostly by deleting the offending section. If anyone has some better wording that could be put in instead, please speak up!

@Gnimuc @fredrikekre @yuyichao If you have time, can you take a glance through the document as it stands right now and let me know if there' s anything else that should be reworded or removed? Thanks.

[kmsquire]

Updated according to the latest review. @vtjnash (or anyone else), would you like to take another quick scan?

The test failure is (probably) #31712.