Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove unnecessary name qualification in docstrings #45898

Merged
merged 1 commit into from
Jul 6, 2022

Conversation

LilithHafner
Copy link
Member

When we give an example usage of an exported name such as

julia> Dates.lastdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-07T00:00:00

We should not qualify the name because this implies (falsely) that lastdayofweek is not exported.

Specifically, any example REPL usage of an exported symbol from a stdlib, when the example comes from a docstring defined by that stdlib, should use the unqualified name. I define "exported" to be Main.sybmol is defined and Main.symbol === Stdlib.symbol.

I made these changes with the following script:

function f()
    stdlibs = filter(readdir("stdlib")) do name
        
        # IDK how _jll's work, but I bet it makes sense to skip them.
        endswith(name, "_jll") && return false

        try
            @eval using $(Symbol(name))
            true
        catch 
            false
        end
    end

    count = 0
    for (root, _, files) in walkdir("stdlib")
        for file in files
            if endswith(file, ".jl")
                replacements = Pair{String, String}[]
                path = joinpath(root, file)

                match = "julia> "
                i = firstindex(match)
                open(path) do f
                    while !eof(f)
                        char = read(f, Char)
                        i = char == match[i] ? i + 1 : firstindex(match)
                        if i == lastindex(match) + 1
                            i = firstindex(match)
                            buff = Char[]
                            while !eof(f)
                                char = read(f, Char)
                                char == '\n' && break
                                push!(buff, char)
                            end
                            str = String(buff)
                            for stdlib in stdlibs
                                if contains(str, stdlib * '.')
                                    loc = findfirst(stdlib * '.', str)
                                    buff2 = Char[]
                                    for i in last(loc)+1:lastindex(str)
                                        char = str[i]
                                        char  vcat('a':'z', 'A':'Z', '0':'9', ['_','!']) || break
                                        push!(buff2, char)
                                    end
                                    str2 = String(buff2)
                                    
                                    if isdefined(Main, Symbol(str2)) && occursin(stdlib, root) && 
                                            @eval(Main.$(Symbol(str2))) === @eval($(Symbol(stdlib)).$(Symbol(str2)))

                                        push!(replacements, "julia> " * str => "julia> " * str[begin:first(loc)-1] * str[last(loc)+1:end])
                                        count += 1
                                    end
                                end
                            end
                        end
                    end
                end

                if !isempty(replacements)
                    contents = read(path, String)
                    contents = replace(contents, replacements...)
                    write(path, contents)
                end
            end
        end
    end
    count
end
for _ in 1:3
    println(f())
end
# 77
# 16
# 0

@LilithHafner LilithHafner added the docs This change adds or pertains to documentation label Jul 1, 2022
@KristofferC KristofferC merged commit b73bf86 into JuliaLang:master Jul 6, 2022
@LilithHafner LilithHafner deleted the unqualified-examples branch July 6, 2022 12:40
ffucci pushed a commit to ffucci/julia that referenced this pull request Aug 11, 2022
Co-authored-by: Lilith Hafner <Lilith.Hafner@gmail.com>
pcjentsch pushed a commit to pcjentsch/julia that referenced this pull request Aug 18, 2022
Co-authored-by: Lilith Hafner <Lilith.Hafner@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants