Considering writing a script to add function signatures to a code base.

[andyDoucette]

This is a great extension! :) I've noticed a few open source projects that don't have function signatures in their docstrings, and I think this package could help a lot.

To help make it easier for me to contribute to these projects, I'd like to write a CLI script that will:

1. Have good help text available for it (-h, and --help). A CLI library like https://github.com/Roger-luo/CLI.jl might be used for this
2. Have the ability to work on a single file or on a whole directory tree (recursively.) It's not clear to me yet if it's a better UI to just do it recursively if a folder is offered instead of a file, or to use a -r flag to have a bit of a sanity check.
3. Have an option to allow the user to specify if they want to add SIGNATURES or TYPEDSIGNATURES, but not both.
4. Print a little warning saying that these are the .jl flies that will be edited. Press enter to confirm.
5. When they press enter, the script removes any existing function signatures and replaces them with $SIGNATURES, ensuring that there is precisely two newlines between that and the next non-white-space character.
6. The script exits, and the user does a "git diff" to double-check that the script did what they wanted.

If I made such a script, and if it worked well (did the right thing 90% of the time, with the other 10% manually fixable), would it be welcomed to be bundled in with DocStringExtensions for others to use as well?

[andyDoucette]

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.

[MichaelHatherly]

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.

[andyDoucette]

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.

[MichaelHatherly]

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.

[andyDoucette]

Thank you very much for those guidelines. They really help reduce the fear factor in submitting a PR because it helps me estimate the chances of rejection/"why don't you do it this way instead" (which is equally invalidating). 🙂 Those two are also my goals so we're 100% in alignment. 😁 I'll send a PR when it's done.

…

On Tue, Sep 28, 2021, 6:45 PM Michael Hatherly ***@***.***> wrote: 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'll 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. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#121 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AEVLQ5V2QCUAGCMA3HIOVCLUEGMERANCNFSM5E4IHANQ> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.