Adopting better standard for file names and related documentation files

[Melkiades]

I found that tern has some functions grouped together in an .R file, while they produce different documentation files. I think this is very confusing when you go from using a function (and its documentation) to accessing or modifying the source code. I propose here to reorganize these functions so as to have a source file per document file. Also, if not utils-files, the source files should be named as the documentation files. The advantages of this approach are beyond clarity. It is better suited to example correction and better for understanding changes in files when a PR is reviewed.

This issue would not break anything at all but as git-diff is file-based, I suggest solving this issue before other PRs, even incrementally if needed. Any feedback is welcome! @gogonzo @shajoezhu

[gogonzo]

Yup I agree and disagree. For example we have a classes for which we write methods. For example FilteredData has filtered_data_new, get_filter_states etc. If we had one file for the single doc-method we would probably end up with too many files. In case of utils which are related to some specific functionality I'd prefer to keep them in single file like grid-utils.R or color-utils.R (instead of all in utils.R).

Good example is dplyr/R/colwise.R https://github.com/tidyverse/dplyr/blob/main/R/colwise.R There are also other colwise like colwise-select.R etc.

So I prefer better grouping instead of having 1-to-1 match between .R and .Rd. But I don't insist as this could be a matter of preference

[Melkiades]

I agree with you. My main concern here is to have unrelated functions inside files that have different exported documentation. This can be problematic to read and modularize at the end. The issue also was opened as a general need for simplifying and splitting long files whenever the grouping is not well defined.

[edelarua]

Hi @Melkiades @gogonzo I've also been looking into this issue and I would suggest that for this specific issue we:

• Clean up the existing structure by breaking up files that are very large/have a large number of functions into a main function .R file and a helper function .R file (e.g. logistic_regression.R currently contains has 17 functions).
• Create .Rd files for helper functions separate from the .Rd files for analysis functions to create less cluttered documentation (and add the helper functions to the See Also section for their related analysis functions)
  • This would also allow us to clean up the tern pkgdown site which does not allow functions that share a .Rd file to be listed separately in the Reference section.

Introducing these changes for now will make some noticeable improvements to the current structure, and we can discuss more organizational changes in the future as we see a need for them so this task does not get too large.

Let me know if you have any thoughts on this. Thanks!

[Melkiades]

I think your proposal is great!!