search

tecosaur / CheckDoc.jl

Documentation linting
MIT License
5 stars 1 forks source link

Trimming verbosity in output #4

Open DanielVandH opened 2 months ago

DanielVandH commented 2 months ago

The output is a bit repetitive currently:

julia> checkdocs(CheckDoc)
 ◀▶ Report on 40 symbols from CheckDoc ━ found 26 possible issues
═════════════════════════════════════════════════════════════════
╭─● CHECKDOC_FACES
│ ┌ 1.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● CHECKS
│ ┌ 2.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● DocIssue
│ ┌ 3.1 Error: undocumented
│ │ All types might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\types.jl:7
╭─● DocsReport
│ ┌ 4.1 Error: undocumented
│ │ All types might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\types.jl:34
╭─● LineNumber
│ ┌ 5.1 Error: undocumented
│ │ All types might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\types.jl:2
╭─● MINIMUM_AST_NODES
│ ┌ 6.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● SEVERITIES
│ ┌ 7.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● SEVERITY_CODES
│ ┌ 8.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● ShortIssue
│ ┌ 9.1 Error: undocumented
│ │ All types might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\types.jl:15
╭─● _astsearch
│ ┌ 10.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:185
╭─● asexpr
│ ┌ 11.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:157
╭─● ast_nodes
│ ┌ 12.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\CheckDoc.jl:233
╭─● astsearch
│ ┌ 13.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:198
╭─● check_args_in_order
│ ┌ 14.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\checks.jl:71
╭─● check_mentions_errors
│ ┌ 15.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\checks.jl:7
╭─● check_missing_args
│ ┌ 16.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\checks.jl:38
╭─● check_missing_kwargs
│ ┌ 17.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\checks.jl:55
╭─● check_non_empty
│ ┌ 18.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\checks.jl:1
╭─● check_signature
│ ┌ 19.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\checks.jl:86
╭─● docfunction
│ ┌ 20.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:200
╭─● getchecks
│ ┌ 21.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\CheckDoc.jl:129
╭─● match_signture
│ ┌ 22.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:162
╭─● maxunion
│ ┌ 23.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:171
╭─● mdfindall
│ ┌ 24.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:3
╭─● recursivedocs
│ ┌ 25.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\CheckDoc.jl:78
╭─● runchecks
│ ┌ 26.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\CheckDoc.jl:141

Would it be better to remove "All <> might as well have a documentation string" and just do e.g. Error: undocumented <>? for example

╭─● SEVERITIES
│ ┌ 7.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● SEVERITY_CODES
│ ┌ 8.1 Error: undocumented
│ │ All variables might as well have a documentation string
╰ └ @ unknown
╭─● ShortIssue
│ ┌ 9.1 Error: undocumented
│ │ All types might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\types.jl:15
╭─● _astsearch
│ ┌ 10.1 Error: undocumented
│ │ All functions might as well have a documentation string
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:185

becomes

╭─● SEVERITIES
│ ┌ 7.1 Error: undocumented variable
╰ └ @ unknown
╭─● SEVERITY_CODES
│ ┌ 8.1 Error: undocumented variable
╰ └ @ unknown
╭─● ShortIssue
│ ┌ 9.1 Error: undocumented type
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\types.jl:15
╭─● _astsearch
│ ┌ 10.1 Error: undocumented function
╰ └ @ C:\Users\User\.julia\packages\CheckDoc\8cdwy\src\utils.jl:185

Also weird that the linenumbers don't seem to know where consts are

tecosaur commented 2 months ago

Thanks for the suggestions. I think you have a point here, I'm just not sure what the best way of going about improving this might be.

Perhaps it would be worth trying grouping together issues of the same type, and only showing the message once (if it's the same for all issues)?

Also weird that the linenumbers don't seem to know where consts are

Currently, I rely on Docs and method instances to indicate where functions/values are sourced from, and undocumented global variables have neither.

DanielVandH commented 2 months ago

Perhaps it would be worth trying grouping together issues of the same type, and only showing the message once (if it's the same for all issues)?

That was my first thought, but I wasn't sure about how much work that might be for you. I imagine an ideal setup would be that it splits the output into something like

Errors
...

Warnings
...

Suggestions
...

Tips
...

and within each category that checks would be grouped, so that e.g. I might see

Undocumented objects: 
    f1 [source line]
    f2 [source line]
    ...

Missing signature:
    g1 [source line]
    g2 [source line]

with apt titles for each of the checks in the CHECKS variable.

How well such an output translates to a terminal display would have to be seen I guess... might be nice if the output was something that could be queried for the four categories if it turns out the display looks a bit rough

tecosaur commented 2 months ago

I think that's pretty sensible. It will take me a bit to get to this, but I'll see about re-arranging the output to be ordered by category, and subcategory.