Structure of lintr documentation

[AshesITR]

Agree it makes sense to have one landing page, but maybe we need

+ available linter suites
└-- linters
└-- google-linters
└-- ...

instead? ?linters is already 300 lines long

Originally posted by @MichaelChirico in #887 (comment)

[AshesITR]

A few ideas off the top of my head regarding this:

• Manually curated "Tree" of manpages linking to relevant linters.
• Function that returns a tibble of all available linters and possibly some metadata (e.g. default yes/no, suite (tidyverse, google, extra)).
• Manually curated vignette with tree-like structure.

[AshesITR]

PyLint has a large interlinked reference containing all linters, much like a vignette.

[MichaelChirico]

great reference for PyLint -- had no idea it comes with so much!

To me what makes the most sense are (1) and (2) [both].

That way something like ?linters lands you at HTML pages you can click around to like you would any documentation; but also something like linter_metadata() can return known linters in a more programmable way.

I'm not sure I see any value of a vignette beyond what those two would offer.

[AshesITR]

How would we split up the linters?
The structure should be as intuitive as possible for a new user who doesn't know about all linters and only has a rough idea of what he might want to be linted.

I'm seeing three major categories: possible coding errors (e.g. missing bindings, missing or extra arguments), sytle / formatting issues (e.g. spacing, naming) and efficiency / portability issues (e.g. unneeded concatenation, undesirable functions, backports).
However I feel the style category is too broad to be useful.

Any thoughts?

[MichaelChirico]

I think you're on the right track. My original thought was that we'd have "tidyverse linters" and "Google linters", but practically it's not very useful/user-friendly. We want a taxonomy that will be more useful to users and I think it's a good start.

Internally I've been tagging our linters with a few keywords:

• readability
• efficiency
• consistency
• best practices

Is there anything stopping us from listing the same linter under multiple categories?

Maybe we should have a Google Spreadsheet with all the linters and possible meta-categories for them and go from there?

[MichaelChirico]

I started a spreadsheet here:

https://docs.google.com/spreadsheets/d/1sE87DFwemUQhhZadNG95UwPvYYYPuVjCZE6f5fuuJkc/edit?usp=sharing

Anyone linked has edit access (🤞) so feel free to adjust the tags / comment. cc @russHyde

Who else should we ping on this effort?

NB: I'm using the CRAN version of lintr so some things will be missing. it's a good start.

[russHyde]

Thanks for including me. Though I appreciate I've largely been absent during the past two years.

[AshesITR]

Thanks for providing a start.
I've worked on the list and removed linters no longer present in master as well as added new linters.

WDYT about including the data on lintr in CSV form in data-raw and using it to

1. provide a data frame to end users and
2. generate RD for each Tag?

I think it would also be useful to add a tag marking default_linters

[AshesITR]

Here are some more thoughts on the interface and documentation structure:

1. Implement lintr::available_linters(tag = NULL, package = "lintr") to return a tibble with columns package <chr>, linter <chr>, tags <lst[chr]>.
2. For each tag create a corresponding roxygen skeleton ?tag_linters which contains autogenerated content based on lintr::available_linters("tag")$linter.
3. Define an interface for available_linters() that can be used by plugin packages, such that available_linters(package = "pkg") finds the lintr metadata for that package. Document this in ?available_linters.
   One suggestion would be a fixed-format CSV located in inst/lintr/linters.csv.
4. Add a test that confirms lintr::available_linters("default")$linter is equivalent to names(lintr::default_linters) to catch documentation mismatch.

A simple way to store the tags would be csv with an, e.g. pipe separated, tag list as a single column.
cc @MichaelChirico

[MichaelChirico]

All sounds good to me.

generate RD for each Tag

How does this work given the one->many mapping of linters->tags? linter is only in the Rd of its primary tag? Or duplicated in all pages where it's tagged? Does Rd support that? Maybe only add an \alias{} to the main tag, but add an entry in all the pages? Does roxygen2 support that?

Define an interface for available_linters() that can be used by plugin packages, such that available_linters(package = "pkg") finds the lintr metadata for that package

Not quite following here, does it mean available_linters(tag = "tag")?

Happy to review CLs for this and should be able to contribute code in the next several weeks

[AshesITR]

All sounds good to me.

generate RD for each Tag

How does this work given the one->many mapping of linters->tags? linter is only in the Rd of its primary tag? Or duplicated in all pages where it's tagged? Does Rd support that? Maybe only add an \alias{} to the main tag, but add an entry in all the pages? Does roxygen2 support that?

I was thinking one help page per linter, linking to all its tag help pages.
The tag pages would link to all linters tagged with the tag, as well as to all other tags (via the family tag, maybe?)

Define an interface for available_linters() that can be used by plugin packages, such that available_linters(package = "pkg") finds the lintr metadata for that package

Not quite following here, does it mean available_linters(tag = "tag")?

That would be a convenience feature to filter the linters based on a tag name, as this functionality would be needed to auto-generate the tag rds anyway.

Happy to review CLs for this and should be able to contribute code in the next several weeks

[AshesITR]

@MichaelChirico I've started a PR #908 to get a feel for what the implementation would look like.
Feel free to try it out and comment.