quoted, jdk (6): Add Scaladoc comments for undocumented entities - #26903
Draft
bvenners wants to merge 3 commits into
Draft
quoted, jdk (6): Add Scaladoc comments for undocumented entities#26903bvenners wants to merge 3 commits into
bvenners wants to merge 3 commits into
Conversation
Documents declarations that had no doc comment at all across scala.jdk (the four accumulators and their shared base, the function wrappers and extensions, the duration and future converters, OptionShape) and the first two files of scala.quoted, Expr and ExprMap. Comment-only: no declaration, body, import, annotation or blank line is touched.
Documents the rest of scala.quoted, most of it Quotes.scala, which alone accounts for 285 newly documented declarations across the reflection API, along with FromExpr, Type, QuoteMatching and StopMacroExpansion. Also revises the scala.jdk documentation added by the previous commit, rechecking each claim against the implementation rather than against the name: the accumulator steppers in particular describe what their guards actually do. Comment-only: no declaration, body, import, annotation or blank line is touched.
Adjudicated from an independent review of this branch. Comment-only. - Quotes.reflect: Closure.apply and TermParamClause.apply documented their arguments as required to satisfy a constraint. Neither is enforced in normal compilation; the assertions run only under -Xcheck-macros. - SelectOuter's `levels` was described as nested scopes of inlined trees. It is stored in OuterSelectName and consumed by ElimOuterSelect as a count of outer-path hops. - FlexibleType's upper bound was called the non-nullable underlying type. FlexibleType.apply takes any value type and uses it as given, so an already nullable type stays nullable. - TreeAccumulator.foldOverTree does not visit the `call` of an Inlined, and TreeMap.transformTree leaves an Export, a Bind's pattern and an Inlined's call untransformed. Both were documented as covering all subtrees. - Accumulator.knownSize said the size does not fit in an Int at Int.MaxValue. It is representable; the bound in the implementation is simply exclusive. - StopMacroExpansion.fillInStackTrace said only a previously reported error is used. A macro can throw it without reporting one, and the compiler then emits its own diagnostic. - asTerm and asExprOf were documented twice: once on the extension clause, as upstream does for a single-method extension, and again on the method by this branch. Since the added comment says strictly more, the older one-liner is dropped so that only one remains. Three @note NEEDS-HUMAN markers are removed, from DoubleAccumulatorStepper .nextStep, LongAccumulatorStepper.nextStep and OmitSelectorMethods.name. They ask questions about the code rather than the documentation, and all three are recorded in todo-writer/docs/suspected-bugs.md. The surrounding documentation was already accurate without them: the steppers' @throws describes the empty accumulator, which is true, and does not claim anything about exhaustion.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR fills in a main doc comment plus @PARAM, @tparam, and @return tags for scala.jdk, scala.quoted and scala.quoted.runtime APIs that are completely missing any Scaladoc documentation. Most of it is quoted/Quotes.scala, which alone accounts for 285 newly documented declarations across the reflection API; the rest covers the scala.jdk accumulators and converters, Expr, ExprMap, FromExpr and Type. I'm submitting it as a draft PR so that I can get the CI to run on it, to see if it breaks anything, and to start getting feedback. We automated the generation of these changes and have not reviewed all of them yet. We will review them all before making the PR non-draft. Please let me know whether you think this is going in the right direction in general, and anything specific that you notice that could be improved.