On Thu, 3 Dec 2020 21:19:38 GMT, Joe Darcy <da...@openjdk.org> wrote:
>> There is lots of other duplication/repetition in most javadoc. I'd rather >> see some kind of text macro that would allow a single definition of a string >> that can be repeated. The source would be a bit less readable, but it would >> be lower maintenance when the same phrase or sentence is repeated to make >> the javadoc more locally complete and easier to read in isolation. Now many >> times do you have to say "throws NullPointerException when the reference is >> null" or similar assertion. > >> >> >> There is lots of other duplication/repetition in most javadoc. I'd rather >> see some kind of text macro that would allow a single definition of a string >> that can be repeated. The source would be a bit less readable, but it would >> be lower maintenance when the same phrase or sentence is repeated to make >> the javadoc more locally complete and easier to read in isolation. Now many >> times do you have to say "throws NullPointerException when the reference is >> null" or similar assertion. > > IMO this is a case to avoid the perfect being the enemy of the good. There > are many structural cases of repeated or nearly repeated return information > in the first sentence and @return tag. Therefore, I think it is reasonable > for don't-repeat-yourself purposes to have dedicated support for this usage > pattern. > > Separately, I agree it would be helpful to have a more general facility to > allow structured placement of repeated text blocks. Yes, there are two patterns being discussed here. 1. The pattern being directly addressed here, which is the local pairwise repetition of Returns the result. @return the result where the repetition is unlikely to occur elsewhere 2. "Disjoint repetition", such as repeated occurrences of @throws IOException if something occurrs which will be found at most once per method, but may appear on many methods We can (separately) discuss #2, preferably in the context of a different JBS issue, and wearing sticky rubber shoes to avoid falling down the cliff of a general macro-substitution language. -- Jon On 12/3/20 1:19 PM, Joe Darcy wrote: > > There is lots of other duplication/repetition in most javadoc. I'd > rather see some kind of text macro that would allow a single > definition of a string that can be repeated. The source would be a > bit less readable, but it would be lower maintenance when the same > phrase or sentence is repeated to make the javadoc more locally > complete and easier to read in isolation. Now many times do you > have to say "throws NullPointerException when the reference is > null" or similar assertion. > > IMO this is a case to avoid the perfect being the enemy of the good. > There are many structural cases of repeated or nearly repeated return > information in the first sentence and @return > <https://urldefense.com/v3/__https://github.com/return__;!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDhTvrReYw$> > > tag. Therefore, I think it is reasonable for don't-repeat-yourself > purposes to have dedicated support for this usage pattern. > > Separately, I agree it would be helpful to have a more general > facility to allow structured placement of repeated text blocks. > > — > You are receiving this because you were mentioned. > Reply to this email directly, view it on GitHub > <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/1355*issuecomment-738325017__;Iw!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDh4e-tvuw$>, > > or unsubscribe > <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRT2VKB4GPG5D2FQJBDSS76HVANCNFSM4T5BHLXA__;!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDjzD260_w$>. > ------------- PR: https://git.openjdk.java.net/jdk/pull/1355
