Considering writing a script to add function signatures to a code base. about docstringextensions.jl HOT 5 CLOSED

My main question is if I made a function that edits the source code (which I'm already 90% done with), would it be considered as an addition to this package? I also have a preference for explicit over implicit/magic, in general.

Feel free to create a PR if you're already that far along implementing and we can weigh up the pros/cons of the approach with something concrete.

Requirements for inclusion in the package would be zero-dependencies outside of Base and general enough to handle any valid Julia syntax that can be documented.

from docstringextensions.jl.

from docstringextensions.jl.

On second thought, with how normal it is for julia devs to work in the repl, maybe I can skip the CLI and it just becomes a function people can access from within julia? Same functionality, just a different interface. Also saves an unnecessary dependency.

from docstringextensions.jl.

On second thought, with how normal it is for julia devs to work in the repl, maybe I can skip the CLI and it just becomes a function people can access from within julia? Same functionality, just a different interface. Also saves an unnecessary dependency.

Yes, just a function-based interface is what would be more useful. (A separate CLI could always be added, but given the precompilation time required in many cases with dev'd packages I doubt many people would use it.)

Another approach that may work better than actually editing the source in that way could be an @autodoc macro that users can just place at the end of their module definition which checks for undocumented bindings and creates an auto-generated docstring for each. A very draft version of how you could go about doing it:

function autodoc(mod::Module)
    docs = Docs.meta(mod)
    for name in names(mod; all = true)
        if isdefined(mod, name)
            binding = Docs.Binding(mod, name)
            if !haskey(docs, binding)
                @eval mod begin
                    @doc """

                    *auto-generated docs*

                    """ $name
                end
            end
        end
    end
end

macro autodoc()
    :(autodoc(@__MODULE__))
end

Has the benefit of not needing the user to run code that changes their source code directly, only an @autodoc call is added to the end of their module.

from docstringextensions.jl.

Very interesting approach! Impressive. Being new to julia, I skipped the section on macros, so I have no idea how this works. The whole macro thing seemed like way too much magic for me anyway, but maybe after a few months I'll see the light.

My main question is if I made a function that edits the source code (which I'm already 90% done with), would it be considered as an addition to this package? I also have a preference for explicit over implicit/magic, in general.

from docstringextensions.jl.