Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documenting private R6 fields ends up in the Public fields section #1145

Closed
CGMossa opened this issue Aug 3, 2020 · 6 comments
Closed

Documenting private R6 fields ends up in the Public fields section #1145

CGMossa opened this issue Aug 3, 2020 · 6 comments

Comments

@CGMossa
Copy link

@CGMossa CGMossa commented Aug 3, 2020

While attempting to document my R6 classes, I encountered this:
When documenting private fields, the field name suddenly appears in the public field's section of
the documentation.

Here's an example

#' An example
#'
#' Class only made to showcase an issue with R6 roxygen documentation
ClassWithPrivateFields <- R6::R6Class(
  classname = "ClassWithPrivateFields",
  private = list(
    #' @field .a_private_field that should be mostly hidden honestly
    .a_private_field = NA
  )
)

And the resulting .Rd file:

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ClassWithPrivateFields.R
\name{ClassWithPrivateFields}
\alias{ClassWithPrivateFields}
\title{An example}
\description{
Class only made to showcase an issue with R6 roxygen documentation
}
\section{Public fields}{
\if{html}{\out{<div class="r6-fields">}}
\describe{
\item{\code{.a_private_field}}{that should be mostly hidden honestly}
}
\if{html}{\out{</div>}}
}
\section{Active bindings}{
\if{html}{\out{<div class="r6-active-bindings">}}
\describe{
\item{\code{.a_private_field}}{that should be mostly hidden honestly}
}
\if{html}{\out{</div>}}
}
\section{Methods}{
\subsection{Public methods}{
\itemize{
\item \href{#method-clone}{\code{ClassWithPrivateFields$clone()}}
}
}
\if{html}{\out{<hr>}}
\if{html}{\out{<a id="method-clone"></a>}}
\if{latex}{\out{\hypertarget{method-clone}{}}}
\subsection{Method \code{clone()}}{
The objects of this class are cloneable with this method.
\subsection{Usage}{
\if{html}{\out{<div class="r">}}\preformatted{ClassWithPrivateFields$clone(deep = FALSE)}\if{html}{\out{</div>}}
}

\subsection{Arguments}{
\if{html}{\out{<div class="arguments">}}
\describe{
\item{\code{deep}}{Whether to make a deep clone.}
}
\if{html}{\out{</div>}}
}
}
}

The above seem hard to understand, here's a screenshot:

image

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Aug 3, 2020

Where do you want the documentation of the private fields go?

@CGMossa
Copy link
Author

@CGMossa CGMossa commented Aug 3, 2020

Honestly, I think Private Fields as a section would be fine. It doesn't need to be more elaborate than this.
Or they shouldn't appear shouldn't appear at all.
Maybe Internal fields sounds more poignant and not easy to confuse with public fields.
Also, I saw that I also got a warning that these private fields are not known. So there's that..

@gaborcsardi
Copy link
Collaborator

@gaborcsardi gaborcsardi commented Aug 3, 2020

Putting the documentation of private fields in the manual is not currently supported. The manual is for the end user, and the end user has no access to these fields, they are not part of the public API of the class.

@CGMossa
Copy link
Author

@CGMossa CGMossa commented Aug 3, 2020

That's fine. Then they should not be included anyways. 
It would still be nice to keep these annotations, if someone ever makes a language server for R, that then can handle showing the documentation on the fly when someone jams in private$..

@greg-minshall
Copy link

@greg-minshall greg-minshall commented Nov 18, 2020

currently (roxygen2 7.1.1) i get errors (or warnings, or notices, ...) when writing documentation for things in R6 private fields. i like using roxygen2 as a template for writing consistent documentation, for public/exported as well as private/non-exported functions/fields.

for me, it would be great to parse and complain about syntax errors, and otherwise ignore private/non-exported.

(so, this applies to non-R6 documentation of non-exported functions from my package, say -- i don't think there is a notice, but i do think they end up being available for > ?nonExportedFunctionFoo, which doesn't seem right.)

thanks for it!

@hadley
Copy link
Member

@hadley hadley commented Apr 16, 2021

Thanks for filing this issue! Unfortunately, I don't think it's a good fit for this package: developing good software requires relentless focus, which means that we have to say no to many good ideas. Even though I'm closing this issue, I really appreciate the feedback, and hope you'll continue to contribute in the future 😄

@hadley hadley closed this as completed Apr 16, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

4 participants