#How do you document runtime-generated code

1 messages · Page 1 of 1 (latest)

summer carbon
#

When using CxxWrap.jl, the behavior is entirely written in C++, then at Julia runtime, the code is loaded into the Julia state. How do I document this? There is no .jl file to use for documenter.jl.

The only way I can think of is to write the docs language-agnostic which I am not a fan of because C++ and Julia are quite different, for example a C++ function Type::foo() would usually be Module.foo!(Type) in Julia, thats different enough notation that people will get confused. It also means that the Julia users would have to know C++, even though the final project is entirely in Julia

#

How do you document runtime-generated code

summer carbon
#

if someone has maybe an exampe of a good julia package that works like this I'd be thankful so I can investigate

#

maybe I can somehow query the julia package tree so it shows me all projects that has CxxWrap.jl as a dependency but idk how to do that

full sun
#

I really want to know the answer to your question too XD
Regarding the Julia package tree, I still want to build a temporal graph of package dependencies, but I had no luck finding time (or a student) to finish my package for this type of structure.

river coyote
#

It sounds to me you should just document the Julia and C++ parts separately. Since the user-facing API is apparently in Julia, document how one uses it in a README. Then on the C++ side, just document it like you would any C++ project. If a user wants the nitty gritty implementation details, they should be willing to dig into some C++.

summer carbon
#

thank you for the respone

#

While I mostly agree, the part of the docs that list all functions in julia will be unavailable which is my problem

#

but it does make sense to basically write the manual twice for each langauge, which is a lot of effort

#

I'm also considering writing the actual text langauge agnostic and then for the code-part of the manual I'll print the exact same behavior once in C++ and once in Julia

#

For example:

Use foo.bar to insert an object into foo

auto foo_instance = Foo();
foo.bar(object);

foo_instance = Foo()
bar(foo, object)
#

I haven't actually started using CxxWrap.jl yet and I'm considering just writing a c-adapter for the library and using that for the Julia binding, then I can use Clang.jl to generate the Julia code so I have an actual .jl file I can document

#

but I think that will be even more work

#

I guess I need to decide if it's a C++ library with a Julia binding or if it's a Julia-library that uses C++

#

oh also the help function in the REPL would be unavailable, even if my docs list the Julia functions using ? in the repl will say it's undocumented if I use CxxWrap.jl

river coyote
summer carbon
#

how would I generate the documenter.jl index and search bar by hand it requires julia code with docstrings to parse

#

the manual I can just write by hand which I would've done anyway but the index of functions and help functionality is unavailable to my users

#

actually I just found out how

# 
julia> undocumented_foo() = return 12
undocumented_foo (generic function with 1 method)

help?> undocumented_foo
search: undocumented_foo

  No documentation found.

  undocumented_foo is a Function.

  # 1 method for generic function "undocumented_foo":
  [1] undocumented_foo() in Main at REPL[1]:1

julia> @doc "is now documented" undocumented_foo
undocumented_foo

help?> undocumented_foo
search: undocumented_foo

  is now documented
#

You can inject documentation at runtime, that way I can just have an index file somewhere and lookup the documentation

#

@full sun idk if this helps for your case since you also wanted to know how to do it

full sun
#

Thank @summer carbon this is good. I need to save that somewhere 😄