Break long docstrings into multiple lines

[stelmo]

This PR should address the issues raised in #120. Currently, long docstrings can become unwieldy to view in the repl. For example, in a package I am developing, this is the first part of the docstring for the function differentiate!:

differentiate!(x::Vector{Float64}, ν::Vector{Float64}, λ::Vector{Float64}, A::Matrix{Float64}, B::Matrix{Float64}, dx::Vector{Float64}, diffmodel::DifferentiableModel, optimizer; modifications, use_analytic, scale_output)

The more types and/or arguments are used, the more difficult it becomes to see what the function signature is. JuliaFormatter.jl breaks docstrings into multiple lines if they are too long. This PR mimics this behavior, so that the docstring for differentiate! becomes:

  differentiate!(
    x::Vector{Float64},
    ν::Vector{Float64},
    λ::Vector{Float64},
    A::Matrix{Float64},
    B::Matrix{Float64},
    dx::Vector{Float64},
    diffmodel::DifferentiableModel,
    optimizer;
    modifications,
    use_analytic,
    scale_output
  )

Basically, a line width flag is used to decide when to break up a method signature, and if it is triggered, then new lines and space delimiters are used to format the docstring. We (@exaexa and I) have made this small patch and updated the tests. Let us know what you think!

[MichaelHatherly]

Thanks for tackling this. I'll try to review in the next few days.

[exaexa]

@MichaelHatherly one question, in the last commit (2cddf0a) I needed to change the version bounds a bit because the julia I used (1.7.something) stubbornly generated the output with the type variable. Is that right?

I failed to find an explanation of why checking for VERSION > v"1.7" would be important, so I can't really tell if the test should fail or not. :]

[MichaelHatherly]

Yeah, there's a number of things that end up dealing with Julia internals and their printing which ends up making some tests a bit temperamental. @kdheepak do you happen to recall that that particular conditional was about?

the julia I used (1.7.something)

What's the exact version that was causing it? I'll attempt to recreate it myself as well for confirmation.

[exaexa]

What's the exact version that was causing it? I'll attempt to recreate it myself as well for confirmation.

I think it was 1.7.0 as downloaded from the web but need to verify. (I'm on another computer now)

[kdheepak]

I added those conditionals based on the Julia version I was using at the time, which usually is the nightly release at the time. I'm not sure if I tested for v1.7 specifically, or if that conditional should be > or >= though, and I can't remember right now.

The commit message just says Fix test failures for Julia 1.8 unfortunately. It would have been nice if I had written out more details there.

That PR / commit was made Oct 22th, and v1.7.0 was released Nov 30th. So I definitely didn't check with a 1.7.x stable release.

[exaexa]

@kdheepak ah ok. I guess it might be useful to use the github matrix to run a oneshot check for correct bounds, as in:

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 3478dbe..9b3c0a1 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -10,6 +10,13 @@ jobs:
       matrix:
         version:
           - '1.0'
+          - '1.1'
+          - '1.2'
+          - '1.3'
+          - '1.4'
+          - '1.5'
+          - '1.6'
+          - '1.7'
           - '1'
           - 'nightly'
         os:

[kdheepak]

I think testing so many jobs limits how many github actions can be run simultaneously on other repos in this organization. If the maintainers are okay with that, it might be worth it.

I'm not sure if the maintainers have formally declared what versions of Julia are supported. For packages I maintain, I usually test only on the latest Julia stable release, the latest nightly and the last LTS.

[exaexa]

@kdheepak some of the test results can be seen here https://github.com/exaexa/DocStringExtensions.jl/runs/6278696972?check_suite_focus=true (a few jobs got cancelled but managed to print out test results in time) -- seems like the current tests fail for all versions between >=1.1 and <1.6. >=1.6 is OK and 1.0 branch is OK too. The test is from this PR, with >= instead of >.

[MichaelHatherly]

I'm not sure if the maintainers have formally declared what versions of Julia are supported. For packages I maintain, I usually test only on the latest Julia stable release, the latest nightly and the last LTS.

I'm fine with updating the julia compat to current LTS (1.6) at this point. Would help reduce CI burden and all the required version checks needed currently. (That should be preferably done as a separate PR though rather than included in here.)

[exaexa]

That should be preferably done as a separate PR though rather than included in here.

Yeah, it's a separate issue and a separate concern. I'll check how problematic it would be for us to have versions restricted to >=1.6 and send a patch in the other case.

Anyway I didn't want this tiny issue to grow over our heads so quickly, esp because it's only for testing reasons in a relatively fragile-specified test. Let's focus on the actual formatting instead :]

[exaexa]

@stelmo I sorted out the tests, actually it's only 1.6.x that shows the special behavior. Could you please pull from here https://github.com/exaexa/DocStringExtensions.jl/commits/mk-fixes ? (the last commit replaces the last one from here, so some --force may be needed)

Ref: see tests on the last 2 commits here https://github.com/exaexa/DocStringExtensions.jl/commits/mk-testall

[stelmo]

Hi, just bumping this a little, I think we sorted out the tests (it looks like codecov is failing, not the package itself)

[exaexa]

@stelmo codecov is complaining about the coverage diff change.

Unfortunately it might be caused by the version checks in the newly added code. I wasn't able to track down any other newly added cover-missing lines.

Locally getting 94.07% cover with Julia from git master, and 93.80% with 1.7.2. 🤔

[MichaelHatherly]

The coverage changes are fine by me, the change isn't that large and it looks like we are covering what needs to be covered.

[MichaelHatherly]

Thanks for the contribution @stelmo and @exaexa.

[exaexa]

@MichaelHatherly thank you!

Any guess if this could be versioned&released soon? (So that --you know-- we can start formatting our ugly long function signatures with DSE? :D :D )

[MichaelHatherly]

Sure, can do.

[MichaelHatherly]

New minor version tagged: JuliaRegistries/General#61075. I've tagged a minor rather than a patch since I feel that altering the formatting that users get probably constitutes a potentially breaking change in some sense...

This will likely be the last version before a 1.0 since nothing significant has changed recently with the package.

[exaexa]

Yes, this IMO demanded a minor according to julia versioning. Thanks again!