I'm trying to migrate much of my current inline documentation to {roxygen2}, but am running into a pretty frustrating situation: the explicit disallowing of {roxygen2} tags to document private members of R6 classes. There are a handful of GitHub issues about this already, including #1145.
While I completely understand the notion that {roxygen2} tags are "for the end user", there's a lot of value to documenting code for ourselves as the developer, too. This way when we return to work on that codepath, we can re-orient ourselves quickly. The problem with {roxygen2} throwing errors (or breaking {pkgdown} pages) for private class members is that it now encourages two different tagging/documenting paradigms in the same codebase.
Have others here encountered this problem (clearly some broadly-speaking have, given the GitHub issues), and if so, how have you solved it? Perhaps it's as simple as something like replacing {roxygen2}'s #' tag prefix with ##', or a more noticeable change like #~? This then allows the same @tag syntax to keep documentation at least appearing relatively consistent throughout code.
I also think there's value in permitting private documentation where the "end user" is the future developer self ... i.e. creating handbooks to aid in future development. A 'private'-mode flag would be quite nice, and is a supported feature of both JavaDoc and Doxygen.