Documenting arguments of $new() that correspond to public fields

[s-fleck]

In my projects it is very common that the arguments of initialize()/$new() correspond to (some of the) the public fields / active bindings of an object. I would expect this pattern to be quite common. Could be get some form of support or best practice guidelines for how to handle this? Copying the description of the @field or just stating something like "see field foobar" both seem suboptimal.

Sorry if this is a bit vague for an issue, I hope this is the appropriate place to ask it.

[gaborcsardi]

just stating something like "see field foobar" both seem suboptimal

So what would be optimal in your opinion?

[s-fleck]

I am not sure. I like the style sphinx uses where it combines the public fields with the constructor documentation (arguably all public fields should be exposed in the constructor anyways). link (see An example class with docstrings and just below the code example there is a link to how it renders)

I have little experience how other doc systems do it, and I'm sure there are several "right" ways. In any case it would be great if there was a "recommended" way for R6, so that we get some uniformity between different packages.

[gaborcsardi]

AFAICT the sphinx example does not say anything about public fields at all.

[s-fleck]

It's implicit. The arguments to the constructor are what end up as public fields. I guess it's a rather simplisitc example, but I would imagine that this is the most common usecase.

Anyways the behavior seems to be configurable in sphinx because it is apparently a somewhat controversial topic (judging from 15 minutes of googling).

[gaborcsardi]

It's implicit. The arguments to the constructor are what end up as public fields.

Well, you can already do this in roxygen2, just leave out the @field tags completely. You'll get a harmless warning about undocumented fields when you run document(), that you can just ignore.

[s-fleck]

Fair enough. It would still be great to get rid of the warnings somehow. Maybe something like @describeIn myclass$initialize or similar could be supported at some point?