335 bring teal_slice and teal_slices to package INDEX

[m7pr]

Proposition on how to solve #335

• Removed @rdname teal_slice from utility functions for teal_slice
• Created customized @usage section to display both teal_slice and utility functions on the same page
• Result: teal_slice appearing in package index, where utility functions only appear in teal_slice documentation page

If this is acceptable, I will do the same for teal_slices

[github-actions]

Code Coverage Summary

Filename                        Stmts    Miss  Cover    Missing
----------------------------  -------  ------  -------  ------------------------------------------------------------------------------------------------------------------------------------------------------
R/calls_combine_by.R                7       0  100.00%
R/choices_labeled.R                49      14  71.43%   25, 36, 41, 51-56, 68, 72-76
R/count_labels.R                   97       0  100.00%
R/filter_panel_api.R               29       1  96.55%   132
R/FilteredData-utils.R             68      25  63.24%   21-24, 27-30, 52-57, 153, 175-184
R/FilteredData.R                  562     227  59.61%   110, 184, 326, 398, 501-510, 533, 554-595, 613-616, 632, 673-706, 721-723, 727-733, 762-790, 813-815, 819-821, 824-838, 842-852, 855-898, 939, 962-984
R/FilteredDataset-utils.R          23       1  95.65%   125
R/FilteredDataset.R               170      61  64.12%   52, 152, 191, 216-273, 312-314
R/FilteredDatasetDataframe.R      121       8  93.39%   87, 148, 158, 234-238
R/FilteredDatasetDefault.R         18       4  77.78%   103-116
R/FilteredDatasetMAE.R            134      37  72.39%   56, 117-122, 161-166, 170-171, 189-211
R/FilterPanelAPI.R                 10       0  100.00%
R/FilterState-utils.R             101       2  98.02%   264, 294
R/FilterState.R                   361      61  83.10%   89, 212, 230-234, 241-242, 256-257, 263-264, 311, 313, 315, 367, 411, 639, 682-705, 715-734, 769-775, 784-790
R/FilterStateChoices.R            341     108  68.33%   310-313, 325, 367, 389-396, 400-417, 445, 458-469, 481-489, 493-522, 543-546, 549-552, 563-586, 597, 602, 613
R/FilterStateDate.R               212     129  39.15%   227, 279-436
R/FilterStateDatettime.R          309     199  35.60%   266, 318-549
R/FilterStateEmpty.R               53      31  41.51%   89, 99-104, 117, 129-169
R/FilterStateExpr.R                75      62  17.33%   149-272
R/FilterStateLogical.R            196     144  26.53%   136, 158, 218, 222-406
R/FilterStateRange.R              408     105  74.26%   262, 384, 510-514, 517-527, 530, 542-548, 559-571, 575-585, 589-591, 605-632, 647, 650, 664-681, 716-721, 731-733
R/FilterStates-utils.R             70       9  87.14%   108, 127, 188-194, 216, 245
R/FilterStates.R                  364      30  91.76%   78-82, 191, 314-323, 411-414, 457, 542-546, 591, 712-715
R/FilterStatesDF.R                  5       0  100.00%
R/FilterStatesMAE.R                10       1  90.00%   40
R/FilterStatesMatrix.R              3       0  100.00%
R/FilterStatesSE.R                211     157  25.59%   36, 71-73, 83-85, 109-116, 124-131, 154-302
R/include_css_js.R                  5       5  0.00%    12-16
R/teal_slice.R                    107       4  96.26%   165, 217-218, 228
R/teal_slices.R                    84       5  94.05%   170-175
R/test_utils.R                     21       0  100.00%
R/utils.R                          18       0  100.00%
R/variable_types.R                 15       8  46.67%   44-51
R/zzz.R                            16      16  0.00%    3-46
TOTAL                            4273    1454  65.97%

Diff against main

Filename      Stmts    Miss  Cover
----------  -------  ------  --------
TOTAL             0       0  +100.00%

Results for commit: 083d0c7

Minimum allowed coverage is 80%

♻️ This comment has been updated with latest results

[chlebowa]

Excellent! 👌 Please proceed with teal_slices.

I would just add a comment line to explain why @usage is used manually, in case we forget in the future.

[github-actions]

Unit Tests Summary

  1 files   29 suites   22s ⏱️
359 tests 359 ✅ 0 💤 0 ❌
824 runs  824 ✅ 0 💤 0 ❌

Results for commit 083d0c7.

♻️ This comment has been updated with latest results.

[m7pr]

Hey @chlebowa proceeded with teal_slices and added comments above @usage section with the motivation for it.
Also added a comment in function's definitions to remember to update the @usage is parameters are edited.

[m7pr]

Will also need to move @param documentation from format.teal_slices to teal_slices and fix R CMD CHECKS.

[chlebowa]

Did you forget to push your changes?

[m7pr]

I think I pushed them, but on wrong branch (334_teal_slice_index@main instead of 335_teal_slice_index@main). Will push here.

[m7pr]

Should be visible on this branch. Sorry!

PS. I will also delete 334_teal_slice_index@main.

[chlebowa]

Please place the @usage section between @details and @params to reflect the structure of the man page better.

Any ideas how to tackle the check warnings?

  Undocumented code objects:
    ‘as.teal_slice’ ‘as.teal_slices’ ‘is.teal_slice’ ‘is.teal_slices’


  Functions or methods with usage in documentation object 'teal_slices' but not in code:
    ‘as.list’ ‘[’ ‘c’ ‘format’ ‘print’


  Objects in \usage without \alias in documentation object 'teal_slice':
    ‘is.teal_slice’ ‘as.teal_slice’ ‘as.list.teal_slice’
    ‘format.teal_slice’ ‘print.teal_slice’
  
  Objects in \usage without \alias in documentation object 'teal_slices':
    ‘is.teal_slices’ ‘as.teal_slices’ ‘as.list’ ‘[’ ‘c’ ‘format’ ‘print’

[m7pr]

Yes, saw those warnings. Will google for the solution. Maybe they need to have their separate documentation pages anyway (not exposed in INDEX). Or we need to add aliases to teal_slice for is.teal_slice and as.teal_slice so that when someone runs ?is.teal_slice the teal_slice page is opened. I'll try with aliases.

[m7pr]

Please place the @Usage section between @details and @params

I moved it between @description and @params. Description comes before the usage, then we have Usage and after that you see Arguments in the documentation page.

[chlebowa]

I tied my hand at removing those warnings and I was only able to remove one. I hope you will find a way.

[m7pr]

I added @aliases and updated @usage section for S3 methods based on this thread https://stackoverflow.com/a/11285863

[m7pr]

Lastly, need to figure out [.teal_slices method entry for a custom @usage and we're good to go.

[m7pr]

OK, this was a bumpy ride, but I figured this out.

Seeing no warnings locally during R CMD CHECK

   Status: OK
   
── R CMD check results ───────────────────────────────────────────────────────────────────────────────────────── teal.slice 0.5.0.9004 ────
Duration: 2m 11.8s

0 errors ✔ | 0 warnings ✔ | 0 notes ✔

R CMD check succeeded

This should be enough to get merged. Pretty cool learning exercise about custom @usage section.

[chlebowa]

[m7pr]

doh

[m7pr]

There was unnecessary extra \ in \\methods. Removed it, thanks for double checking.

[m7pr]

But now I do see as.teal_slice(s) and is.teal_slice(s) in package index. So this needs a bit more investigation.

[chlebowa]

Nice job 👌

[chlebowa]

But now I do see as.teal_slice(s) and is.teal_slice(s) in package index. So this needs a bit more investigation.

So are all the methods ☹️

[chlebowa]

Not quite there yet.

[m7pr]

So adding @aliases like

#' @aliases is.teal_slices as.teal_slices as.list.teal_slices format.teal_slices print.teal_slices c.teal_slices [.teal_slices

list those functions as topics in package index.

But if you do not have those as @aliases, then R CMD CHECK throws:

W  checking for missing documentation entries (1.3s)
   Undocumented code objects:
     'as.teal_slices' 'is.teal_slices'
   All user-level objects in a package should have documentation entries.
   See chapter 'Writing R documentation files' in the 'Writing R
   Extensions' manual.
✔  checking for code/documentation mismatches (3.1s)
W  checking Rd \usage sections (854ms)
   Objects in \usage without \alias in documentation object 'teal_slices':
     'is.teal_slices' 'as.teal_slices' 'as.list.teal_slices'
     '[.teal_slices' 'c.teal_slices' 'format.teal_slices'
     'print.teal_slices'
   
   Functions with \usage entries need to have the appropriate \alias
   entries, and all their arguments documented.
   The \usage entries must correspond to syntactically valid R code.
   See chapter 'Writing R documentation files' in the 'Writing R
   Extensions' manual.

A dead end.

[chlebowa]

Maybe there is a way to edit ~/R/x86_64-pc-linux-gnu-library/4.3/teal.slice/html/00Index.html directly?

[m7pr]

@chlebowa I tired with the INDEX file #335 (comment)
The index.html probably gets created during package installation. Not a part of the source doe.

[chlebowa]

Probably, yeah.
But INDEX is all right:

~/R/x86_64-pc-linux-gnu-library/4.3/teal.slice:$ more INDEX
FilterPanelAPI          Class to encapsulate the API of the filter
                        panel of a teal app
filter_state_api        Managing 'FilteredData' states
get_filter_expr         Gets filter expression for multiple 'datanames'
                        taking into account its order.
init_filtered_data      Initialize 'FilteredData'
teal_slice              Specify single filter
teal_slices             Complete filter specification

[m7pr]

So I figured this INDEX file does not have any influence on anything : P

[m7pr]

I've got 2 more ideas. Will experiment with @noRd / @rdname tags, nor no tags for utility functions WITH removed @aliases tag.

[m7pr]

My final idea was to (for each utility function) create a small documentation page

#' @title `is.teal_slices`
#' @description Utility function for [`teal_slices`] object.
#' @export
#' @keywords internal
#'

that is not listed in package index (thanks to @keywords internal).

If user hits ?teal_slices (s)he will see an overview of teal_slices with a custom @usage. Is (s)he hits ?is.teal_slices (s)he will have a change to get redirected directly to ?teal_slices.

However **R CMD CHECK throws a warning about missing aliases for teal_slices **

W  checking Rd \usage sections (854ms)
   Objects in \usage without \alias in documentation object 'teal_slices':
     'is.teal_slices' 'as.teal_slices' 'as.list.teal_slices'
     '[.teal_slices' 'c.teal_slices' 'format.teal_slices'
     'print.teal_slices'

[m7pr]

I think I will need to take a break from this. Or we end up with a proposition from #335 (comment) where we have utility functions documented on a separate page, but they are linked from ?teal_slices in the description part.