[9] RFR 8138838: docs cleanup for java.desktop (original) (raw)

Alexander Stepanov alexander.v.stepanov at oracle.com
Mon Oct 5 11:15:19 UTC 2015

Sorry; wrong subject...

On 10/5/2015 2:12 PM, Alexander Stepanov wrote:

Hello,

Could you please review the fix for https://bugs.openjdk.java.net/browse/JDK-8138838 Patch + webrev zipped + specdiff report: http://cr.openjdk.java.net/~avstepan/8138838 Just some cosmetic changes for docs (... -> {@code ...} replacement) + some misprints fixed. Not sure if these changes are desired at all for now. Thanks, Alexander (Just in case, adding the prehistory and sending a copy to core-libs-dev).

On 10/1/2015 2:31 PM, Alexander Stepanov wrote: Hello Martin, Stuart, Thank you for the notes, Yes, the initial utility is quite ugly, I just tried to prepare it as quickly as possible hoping that it covers the majority of "trivial" replace cases. Yes, it does not process multi-line inclusions. > s = s.replace( "", tag1); > s = s.replace( "", tag1); > s = s.replace("", tag2); > s = s.replace("", tag2); - replaced with "s = ln.replaceAll("(?i)", "").replaceAll("(?i)", "");" Unfortunately my Perl/lisp knowledge are zero :) > Should you publish your specdiff? I guess not - it would be empty! For now it contains a single fixed misprint diff, but there are a few another misprints at the moment which I'd like to include in the patch as well. So if you don't have objections, I'll delay for a several days and then publish a final RFR (probably containing changes in some other repos like jaxws, corba or jaxp) which would be more formal (containing bug # and the final specdiff report). Thanks again, Alexander

On 10/1/2015 9:54 AM, Martin Buchholz wrote: Hi s'marks, You probably don't need to absolutify paths. And you can easily handle multiple args. (just for fun!) Checks for javadoc comment; handles popular html entities; handles multiple lines; handles both tt and code: #!/bin/bash _find "$@" -name '.java' | _ _xargs -r perl -p0777i -e _ 'do {} while s~^ _*.\K<(tt|code)>((?:[^<>{}&@]|&(?:lt|gt|amp);))</\1>$=$2;_ _s/</</g; s/>/>/g; s/&/&/g; "{@code $}"mgie'_

On Wed, Sep 30, 2015 at 6:16 PM, Stuart Marks <stuart.marks at oracle.com <mailto:stuart.marks at oracle.com>> wrote: Hi Alexander, Martin, The challenge of Perl file slurping and Emacs one-liners was too much to bear. This is Java, so one-liners are hardly possible. Still, there are a bunch of improvements that can be made to the Java version. (OK, and I'm showing off a bit.) Take a look at this: http://cr.openjdk.java.net/~smarks/misc/SimpleTagEditorSmarks1.java <http://cr.openjdk.java.net/%7Esmarks/misc/SimpleTagEditorSmarks1.java> I haven't studied the output exhaustively, but it seems to do a reasonably good job for the common cases. I ran it over java.lang and I noticed a few cases where there is markup embedded within text, which should be looked at more closely. I don't particularly care if you use my version, but there are some techniques that I'd strongly recommend that you consider using in any such tool. In particular: - Pattern.DOTALL to do multi-line matches - Pattern.CASEINSENSITIVE - try-with-resources to ensure that files are closed properly - NIO instead of old java.io <http://java.io> APIs, particularly Files.walk() and streams - use Scanner to deal with input file buffering - Scanner's stream support (I recently added this to JDK 9) Enjoy, s'marks

On 9/29/15 2:23 PM, Martin Buchholz wrote: Hi Alexander, your change looks good. It's OK to have manual corrections for automated mega-changes like this, as long as they all revert changes. Random comments: Should you publish your specdiff? I guess not - it would be empty! while((s = br.readLine()) != null) { by matching only one line at a time, you lose the ability to make replacements that span lines. Perlers like to "slurp" in the entire file as a single string. s = s.replace( "", tag1); s = s.replace( "", tag1); s = s.replace("", tag2); s = s.replace("", tag2); Why not use case-insensitive regex? Here's an emacs-lisp one-liner I've been known to use: (defun tt-code () (interactive) (query-replace-regexp "<\(tt\|code\)>\([^&<>\\]+\)</\1>" "{@code \2}")) With more work, one can automate transformation of embedded things like <_ _But of course, it's not even possible to transform ALL uses of_ _ to {@code, if there was imaginative use of nested html tags. On Tue, Sep 29, 2015 at 3:21 AM, Alexander Stepanov <_ _alexander.v.stepanov at oracle.com_ _alexander.v.stepanov at oracle.com>> wrote: Updated: a few manual corrections were made (as @linkplain tags displays nested {@code } literally): http://cr.openjdk.java.net/~avstepan/tmp/codeTags/jdk.patch <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/jdk.patch> -checked with specdiff (which of course does not cover documentation for internal packages), no unexpected diffs detected. Regards, Alexander On 9/27/2015 4:52 PM, Alexander Stepanov wrote: Hello Martin, Here is some simple app. to replace tags with a new-style {@code } one (which is definitely not so elegant as the Perl one-liners): http://cr.openjdk.java.net/~avstepan/tmp/codeTags/SimpleTagEditor.java <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/SimpleTagEditor.java> Corresponding patch for jdk and replacement log (~62k of the tag changes): http://cr.openjdk.java.net/~avstepan/tmp/codeTags/jdk.patch <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/jdk.patch> http://cr.openjdk.java.net/~avstepan/tmp/codeTags/replace.log <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/replace.log> (sorry, I have to check the correctness of the patch with specdiff yet, so this is rather demo at the moment). Don't know if these changes (cosmetic by nature) are desired for now or not. Moreover, probably some part of them should go to another repos (e.g., awt, swing -> "client" instead of "dev"). Regards, Alexander

More information about the core-libs-dev mailing list