Document UI in a single `.Rd` file

[IndrajeetPatil]

trafficstars

Closes #971

[codecov-commenter]

Codecov Report

Merging #972 (679f2d7) into main (3414b81) will increase coverage by 0.17%. The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #972      +/-   ##
==========================================
+ Coverage   89.89%   90.07%   +0.17%     
==========================================
  Files          47       47              
  Lines        2653     2660       +7     
==========================================
+ Hits         2385     2396      +11     
+ Misses        268      264       -4     

Impacted Files	Coverage Δ
R/ui-styling.R	100.00% <ø> (ø)
R/rules-spaces.R	98.33% <0.00%> (ø)
R/detect-alignment.R	97.75% <0.00%> (+0.02%)	:arrow_up:
R/detect-alignment-utils.R	97.22% <0.00%> (+6.31%)	:arrow_up:

Help us with your feedback. Take ten seconds to tell us how you rate us.

[github-actions[bot]]

This is how benchmark results would change (along with a 95% confidence interval in relative change) if 96869c2333a78c92eda9fb2a8b8fe9b3f3166d0c is merged into main:

•   :ballot_box_with_check:cache_applying: 30.8ms -> 30.7ms [-1.11%, +0.68%]
•   :ballot_box_with_check:cache_recording: 1.3s -> 1.3s [-0.9%, +0.73%]
•   :ballot_box_with_check:without_cache: 3.42s -> 3.42s [-0.6%, +0.4%]

Further explanation regarding interpretation and methodology can be found in the documentation.

[IndrajeetPatil]

@lorenzwalthert This should be ready for a review.

[IndrajeetPatil]

bump

[lorenzwalthert]

Hi @IndrajeetPatil. After looking at the product (help file), I decided that I don't actually think it's a good idea to document these functions in the same file. Here's why:

• Bigger helpfile: Because of the way {roxygen2} formats the help file, we now have to scroll quite a bit to get to the arguments.
• Order of arguments in Usage section =! order of arguments in Arguments: The path argument comes second last, but it's the first argument in style_file(). There is no way of aligning Usage and Argument section in one file.
• Since we have a See also section, it's easy to find other function from the same family.
• The {pkgdown} index already groups relevant functions in the online docs.
• The example section contains now examples from different functions.

Sorry to change my mind after your implementation work. But as I said, I don't think duplication is a problem at the reader side. It's actually desired (Do repeat yourself). Unlike many other doc systems, roxygen allows inheritance, so we can actually generate duplication for the end user's docs without writing docs multiple times.

[lorenzwalthert]

If you want, you could change this PR to harmonizing the sections in the different help files, but I can also understand if you don't feel like it anymore 😒

[IndrajeetPatil]

No worries, @lorenzwalthert.

If you think this leads to deterioration in the user experience while reading the docs, then, yes, it's not ideal. Maybe I shouldn't be drawing too close of a parallel with {lintr}, and maybe I should also discount my own experience with reading these docs since I am already quite familiar with them.

you could change this PR to harmonizing the sections in the different help files

I can probably handle this in a separate PR.

[lorenzwalthert]

ok, thanks @IndrajeetPatil for being kind with me.

[IndrajeetPatil]

Btw, given that I've been contributing and will continue to contribute to this repo, do you think it makes sense to add me as a contributor to the repo, so that-

1. I don't need to work from a fork and keep it up-to-date
2. Label issues
3. Update branches when the need be
4. Re-open old issues in case of a regression, or while revisiting it in the future
5. etc.

I am already a contributor on the {lintr} repo, and the team there can attest to the fact that I am well-behaved 😅

cc @krlmlr

[lorenzwalthert]

@IndrajeetPatil I invited you to be a collaborator of {styler}. We are happy to have you and look forward to your next contributions. I plan to reduce my engagement with {styler} in the future, so it's great that you have decided to increase yours.

[IndrajeetPatil]

Thanks a lot ☺️

Excited to be part of the team, and looking forward to contributing more!