sample versioning directives, empty + description #24160
Conversation
|
I guess we should have discussed the threshold for this. I naively thought just for new methods or classes. What do other libraries do? |
|
Yeah I realized it was weird cause we use what's new for lots of what's changed and have almost no non-deprecation API changes |
Which is a good thing (API stability 👍). Additions/extensions are in "What's new". Almost all other changes should have deprecations. |
|
Is there preference for the summary or blank version? If yes, should I document that in #24161? Also any styling preferences? |
eb647ac to
802b89f
Compare
Whether a comment makes semse depends is case-by-case: If the whole thing (function/parameter/...) is new there is nothing more to say. If only part is new, like in the {}-style example, that should be documented. If you want to be very explicit, you can document that, but I would also be ok to not write that out in text but add one more example with such a summary. |
802b89f to
cfa28b0
Compare
Co-authored-by: melissawm <melissawm@gmail.com> Co-authored-by: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com>
434735a to
7c3b627
Compare
Based on discussion on call and in #23506, trying out some versioning directives. Policy at #24161
Haven't styled anything yet, tried w/o and w/ description cause wasn't sure what made more sense. I guess w/o is a pointer to go look up those release notes, but not sure how to document that. The issue is that these two are partially new things - polar errobars and more valid parameter values, rather than wholly new things.