Review docstrings of all packages

[kennedy-mindermann]

Review & update all packages to ensure every publicly exported type/method has a docstring:

• PowerSystems
• PowerFlows
• PowerSimulationsDynamics
• PowerNetworkMatrices
• SiennaPRASInterface
• InfrastructureSystems
• PowerSystemCaseBuilder
• HydroPowerSimulations
• PowerAnalytics
• PowerGraphics

Deprioritized:

• PowerSimulations

[luke-kiernan]

This prompt worked pretty well for me, with Claude code on PSY and IS. The addition of "use a multi-line regex" makes it get done much faster than it would otherwise.

"Use a multi-line regex to find all exported types and methods that do not have docstrings. Then, use the written documentation in the docs folder to create a docstring for each: if you reference other types or methods in that docstring, include a @ref so that there's a link in the built documentation. If no info is available on the type or method, then leave a comment saying #TODO DOCS. Build the documentation and make sure any additions didn't cause any new errors."

[luke-kiernan]

IS: PR #554.
PSY: PR #1632
PNM: PR #255
PF: all exports documented already.
PSB: all exports documented already.

For IS, all the direct exports are documented already, but I had to add docstrings for some re-exports from PSY.

Useful script, just find-and-replace `PowerSystemCaseBuilder` with package name

using PowerSystemCaseBuilder

function check_exported_docs(mod, modname)
    missing_types = Vector{String}()
    missing_funcs = Vector{String}()
    missing_other = Vector{String}()
    ndoc = 0
    errored = Vector{String}()
    for n in names(mod)
        n == Symbol(modname) && continue
        n == :eval && continue
        n == :include && continue
        obj = try
            getfield(mod, n)
        catch
            continue
        end
        obj isa Module && continue
        has_doc = try
            doc = Base.Docs.doc(obj)
            docstr = string(doc)
            !startswith(docstr, "No documentation found")
        catch e
            push!(errored, "$(string(n)): $(e)")
            # If doc rendering errors, it likely has a docstring (just broken template)
            true
        end
        if !has_doc
            if obj isa Type || obj isa UnionAll
                push!(missing_types, string(n))
            elseif obj isa Function
                push!(missing_funcs, string(n))
            else
                push!(missing_other, string(n))
            end
        else
            ndoc += 1
        end
    end
    return missing_types, missing_funcs, missing_other, ndoc, errored
end

println("=== PowerSystemCaseBuilder.jl Exported Symbols Without Docstrings ===")
mt, mf, mo, nd, errs = check_exported_docs(PowerSystemCaseBuilder, "PowerSystemCaseBuilder")
println("\nTypes without docs ($(length(mt))):")
for t in sort(mt)
    println("  $t")
end
println("\nFunctions without docs ($(length(mf))):")
for f in sort(mf)
    println("  $f")
end
if !isempty(mo)
    println("\nOther without docs ($(length(mo))):")
    for o in sort(mo)
        println("  $o")
    end
end
if !isempty(errs)
    println("\nErrored during doc check ($(length(errs))):")
    for e in errs
        println("  $e")
    end
end
println("\nDocumented exported symbols: $nd")
println("Total exported symbols: $(length(names(PowerSystemCaseBuilder)) - 1)")

[luke-kiernan]

Should every instance of each exported method have a docstring, or it is sufficient for just one instance to have a docstring? The above script assumes the second

edit: conclusion is that "it depends." If the interface is fairly uniform, then no need; if they're substantially different, then yes. So look at the number of args, whether the args have a common super type, etc. and use your judgement.