<Swing Dev> [14] RFR JDK-8227607: Broken external links in java.desktop

Phil Race philip.race at oracle.com
Wed Dec 11 18:36:18 UTC 2019


+1

-phil.

On 12/10/19 2:12 AM, Prasanta Sadhukhan wrote:
>
> Modified webrev: http://cr.openjdk.java.net/~psadhukhan/8227607/webrev.3/
>
> with updated spec 
> http://cr.openjdk.java.net/~psadhukhan/8227607/docs1/api/java.desktop/javax/swing/text/Document.html
>
> Regards
>
> Prasanta
>
> On 09-Dec-19 11:00 PM, Philip Race wrote:
>> >
>>
>>   * ||
>>     <http://cr.openjdk.java.net/%7Epsadhukhan/8227607/docs/api/java.desktop/javax/swing/text/Document.html#putProperty%28java.lang.Object,java.lang.Object%29>
>>
>>
>> For more information on the |Document| class, see The Swing 
>> Connection 
>> <http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html> 
>>
>>
>>
>> This link above  seems to be obsolete as well. I think it should just 
>> be removed
>>
>> > If an element is a a leaf,isLeaf() returns true.
>>
>> add a space after the comma.
>>
>> Also can we wrap all  - or at least the ones that make sense - API 
>> references in {@code ... }  ?
>>
>> Method calls for sure.
>>
>> interrface -> interface.
>>
>> -phil.
>>
>> On 12/9/19, 3:16 AM, Prasanta Sadhukhan wrote:
>>>
>>> Modified version with new subtitle ""Overview and Programming Tips" 
>>> and graphical_schema
>>>
>>> http://cr.openjdk.java.net/~psadhukhan/8227607/webrev.2/
>>>
>>> spec change will look like 
>>> http://cr.openjdk.java.net/~psadhukhan/8227607/docs/api/java.desktop/javax/swing/text/Document.html
>>>
>>> Regards
>>> Prasanta
>>> On 08-Dec-19 1:47 AM, Philip Race wrote:
>>>> I got very confused as to whether there was even an updated version 
>>>> here.
>>>> This conversation became too complex for the inline diff.
>>>> I think that it would be best to first generate a webrev put it on cr.
>>>>
>>>>
>>>> I do think we need to have a subtitle that prefaces this new 
>>>> content rather
>>>> than just appending it to "Properties" ..
>>>>
>>>> I suggest "Overview and Programming Tips" which makes it clearer it 
>>>> is not (so much) specification as developer guide.
>>>>
>>>> > Swing has a interesting interface, called the _|Element| 
>>>> <http://cr.openjdk.java.net/%7Epsadhukhan/docs/api/java.desktop/javax/swing/text/Element.html>_,
>>>>
>>>> I do think this needs rephrasing.
>>>>
>>>> "Element is an important interface used in constructing a Document.
>>>> It has the power ...."
>>>>
>>>> And each time it says "In Swing" I think, why does it bother saying 
>>>> that ...
>>>> confusion with an SGML Element ?
>>>> Maybe it would read better written as "In the Swing text API's 
>>>> document model"
>>>>
>>>> -phil.
>>>>
>>>> On 12/6/19, 7:22 PM, Prasanta Sadhukhan wrote:
>>>>> Anything more needs to be added?!!! Can it be committed?
>>>>>
>>>>> On 06-Dec-19 9:49 AM, Prasanta Sadhukhan wrote:
>>>>>> I guess I already shared... 
>>>>>> http://cr.openjdk.java.net/~psadhukhan/docs/api/java.desktop/javax/swing/text/Document.html
>>>>>>
>>>>>> Regards
>>>>>>
>>>>>> Prasanta
>>>>>>
>>>>>> On 06-Dec-19 4:44 AM, Sergey Bylokhov wrote:
>>>>>>> Hi, Prasanta.
>>>>>>>
>>>>>>> Can you please share the final generated JavaDoc, it is hard to 
>>>>>>> read the diff below.
>>>>>>>
>>>>>>> On 12/4/19 10:09 am, Prasanta Sadhukhan wrote:
>>>>>>>> Inlined information from element_interface page into Document 
>>>>>>>> class <spec will look like 
>>>>>>>> http://cr.openjdk.java.net/~psadhukhan/docs/api/java.desktop/javax/swing/text/Document.html]
>>>>>>>>
>>>>>>>> /diff -r 53eff6c5da11 
>>>>>>>> src/java.desktop/share/classes/javax/swing/Timer.java/
>>>>>>>>
>>>>>>>> --- a/src/java.desktop/share/classes/javax/swing/Timer.java Sun 
>>>>>>>> Oct 06 21:42:50 2019 -0700
>>>>>>>> +++ b/src/java.desktop/share/classes/javax/swing/Timer.java Wed 
>>>>>>>> Dec 04 22:07:48 2019 +0530
>>>>>>>> @@ -124,13 +124,6 @@
>>>>>>>>    * <a 
>>>>>>>> href="https://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html" 
>>>>>>>>
>>>>>>>>    * target = "_top">How to Use Timers</a>,
>>>>>>>>    * a section in <em>The Java Tutorial.</em>
>>>>>>>> *- * For more examples and help in choosing between**
>>>>>>>> **- * this <code>Timer</code> class and**
>>>>>>>> **- * <code>java.util.Timer</code>,**
>>>>>>>> **- * see**
>>>>>>>> **- * <a 
>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/timer/"**
>>>>>>>> **- * target="_top">Using Timers in Swing Applications</a>,**
>>>>>>>> **- * an article in <em>The Swing Connection.</em>**
>>>>>>>> *  * <p>
>>>>>>>>    * <strong>Warning:</strong>
>>>>>>>>    * Serialized objects of this class will not be compatible with
>>>>>>>>
>>>>>>>> /diff -r 53eff6c5da11 
>>>>>>>> src/java.desktop/share/classes/javax/swing/text/Document.java/
>>>>>>>>
>>>>>>>> --- 
>>>>>>>> a/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>> Sun Oct 06 21:42:50 2019 -0700
>>>>>>>> +++ 
>>>>>>>> b/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>> Wed Dec 04 22:07:48 2019 +0530
>>>>>>>> @@ -167,9 +167,38 @@
>>>>>>>>    *
>>>>>>>>    * <p>For more information on the <code>Document</code> 
>>>>>>>> class, see
>>>>>>>>    * <a 
>>>>>>>> href="http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html">The 
>>>>>>>> Swing Connection</a>
>>>>>>>> *- * and most particularly the article,**
>>>>>>>> **- * <a 
>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">**
>>>>>>>> **- * The Element Interface</a>.**
>>>>>>>> **+ * <p>Swing has a interesting interface, called the 
>>>>>>>> <u>{@link javax.swing.text.Element}</u>, **
>>>>>>>> **+ * which has the power to describe various structural parts 
>>>>>>>> of a document, **
>>>>>>>> **+ * such as paragraphs, lines of text, or even (in HTML 
>>>>>>>> documents) items in lists. **
>>>>>>>> **+ * Conceptually, the Element interface captures some of the 
>>>>>>>> spirit of an SGML document. **
>>>>>>>> **+ * So if you know SGML, you may already have some 
>>>>>>>> understanding of Swing's Element interface.**
>>>>>>>> **+ * <p>In Swing, the interface Element defines a structural 
>>>>>>>> piece of a Document, **
>>>>>>>> **+ * like a paragraph, a line of text, or a list item in an 
>>>>>>>> HTML document.**
>>>>>>>> **+ * <p>Every Element is either a branch or a leaf. If an 
>>>>>>>> element is a branch, **
>>>>>>>> **+ * the isLeaf() method returns false. If an element is a a 
>>>>>>>> leaf,isLeaf() returns true.**
>>>>>>>> **+ * <p>Branches can have any number of children. Leaves do 
>>>>>>>> not have children. **
>>>>>>>> **+ * To determine how many children a branch has, you can call 
>>>>>>>> getElementCount(). **
>>>>>>>> **+ * To determine the parent of an Element, you can call 
>>>>>>>> getParentElement(). **
>>>>>>>> **+ * Root elements don't have parents, so calling 
>>>>>>>> getParentElement() on a root returns null.**
>>>>>>>> **+ * <p>An Element represents a specific region in a Document 
>>>>>>>> that begins with startOffset **
>>>>>>>> **+ * and ends just before endOffset. **
>>>>>>>> **+ * The start offset of a branch Element is usually the start 
>>>>>>>> offset of its first child. **
>>>>>>>> **+ * Similarly, the end offset of a branch Element is usually 
>>>>>>>> the end offset of its last child.**
>>>>>>>> **+ * <p>Every Element is associated with an AttributeSet that 
>>>>>>>> you can access by calling getAttributes(). **
>>>>>>>> **+ * In an Element, and AttributeSet is essentially a set of 
>>>>>>>> key/value pairs. **
>>>>>>>> **+ * These pairs are generally used for markup -- such as 
>>>>>>>> determining the Element's **
>>>>>>>> *
>>>>>>>>
>>>>>>>> *+ * foreground color, font size, and so on. But it is up to 
>>>>>>>> the model, and the developer, **
>>>>>>>> **+ * to determine what is stored in the AttributeSet.**
>>>>>>>> **+ * <p>You can obtain the root Element (or Elements) of a 
>>>>>>>> Document by calling the **
>>>>>>>> **+ * methods getDefaultRootElement() and getRootElements(), 
>>>>>>>> which are defined in the Document interface.**
>>>>>>>> **+ * <p>The Document interrface is responsible for translating 
>>>>>>>> a linear view of the **
>>>>>>>> **+ * characters into Element operations. It is up to each 
>>>>>>>> Document implementation **
>>>>>>>> **+ * to define what the Element structure is.**
>>>>>>>> **+ * <p>It is recommended to look into {@link 
>>>>>>>> javax.swing.text.EditorKit} and **
>>>>>>>> **+ * {@link javax.swing.text.View}.**
>>>>>>>> **+ * View is responsible for rendering a particular Element, 
>>>>>>>> and **
>>>>>>>> **+ * EditorKit is responsible for a ViewFactory that is able 
>>>>>>>> to decide what **
>>>>>>>> **+ * View should be created based on an Element.*
>>>>>>>>
>>>>>>>> Regards
>>>>>>>>
>>>>>>>> Prasanta
>>>>>>>>
>>>>>>>> On 04-Dec-19 10:45 AM, Sergey Bylokhov wrote:
>>>>>>>>> On 12/3/19 9:08 pm, Prasanta Sadhukhan wrote:
>>>>>>>>>> Hi Sergey,
>>>>>>>>>>
>>>>>>>>>> I could not find the page for element_interface itself so how 
>>>>>>>>>> to get the information from there?
>>>>>>>>>
>>>>>>>>> I guess it is the same as you posted before:
>>>>>>>>> https://web.archive.org/web/20120418045506/http://java.sun.com/products/jfc/tsc/articles/text/element_interface/ 
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>> Regards
>>>>>>>>>>
>>>>>>>>>> Prasanta
>>>>>>>>>>
>>>>>>>>>> On 04-Dec-19 7:31 AM, Sergey Bylokhov wrote:
>>>>>>>>>>> Hi, Prasanta.
>>>>>>>>>>> Probably we can inline some information from the 
>>>>>>>>>>> element_interface.html to the JavaDoc itself? The JavaDoc 
>>>>>>>>>>> already has some similar schemes.
>>>>>>>>>>>
>>>>>>>>>>> On 12/2/19 2:37 am, Prasanta Sadhukhan wrote:
>>>>>>>>>>>> Hi All,
>>>>>>>>>>>>
>>>>>>>>>>>> Please review a doc-fix for removing some dead links from 
>>>>>>>>>>>> the specifications. These links were part of java.sun.com 
>>>>>>>>>>>> but has not been migrated to docs.oracle.com so it's better 
>>>>>>>>>>>> to remove them
>>>>>>>>>>>>
>>>>>>>>>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-8227607
>>>>>>>>>>>>
>>>>>>>>>>>> diff -r 7637e77c4c8a 
>>>>>>>>>>>> src/java.desktop/share/classes/javax/swing/Timer.java
>>>>>>>>>>>> --- a/src/java.desktop/share/classes/javax/swing/Timer.java 
>>>>>>>>>>>> Mon Dec 02 11:58:14 2019 +0530
>>>>>>>>>>>> +++ b/src/java.desktop/share/classes/javax/swing/Timer.java 
>>>>>>>>>>>> Mon Dec 02 16:02:08 2019 +0530
>>>>>>>>>>>> @@ -124,13 +124,6 @@
>>>>>>>>>>>>    * <a 
>>>>>>>>>>>> href="https://docs.oracle.com/javase/tutorial/uiswing/misc/timer.html" 
>>>>>>>>>>>>
>>>>>>>>>>>>    * target = "_top">How to Use Timers</a>,
>>>>>>>>>>>>    * a section in <em>The Java Tutorial.</em>
>>>>>>>>>>>> *- * For more examples and help in choosing between**
>>>>>>>>>>>> **- * this <code>Timer</code> class and**
>>>>>>>>>>>> **- * <code>java.util.Timer</code>,**
>>>>>>>>>>>> **- * see**
>>>>>>>>>>>> **- * <a 
>>>>>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/timer/"**
>>>>>>>>>>>> **- * target="_top">Using Timers in Swing Applications</a>,**
>>>>>>>>>>>> **- * an article in <em>The Swing Connection.</em>*
>>>>>>>>>>>>    * <p>
>>>>>>>>>>>>    * <strong>Warning:</strong>
>>>>>>>>>>>>    * Serialized objects of this class will not be 
>>>>>>>>>>>> compatible with
>>>>>>>>>>>> diff -r 7637e77c4c8a 
>>>>>>>>>>>> src/java.desktop/share/classes/javax/swing/text/Document.java
>>>>>>>>>>>> --- 
>>>>>>>>>>>> a/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>>>>>> Mon Dec 02 11:58:14 2019 +0530
>>>>>>>>>>>> +++ 
>>>>>>>>>>>> b/src/java.desktop/share/classes/javax/swing/text/Document.java 
>>>>>>>>>>>> Mon Dec 02 16:02:08 2019 +0530
>>>>>>>>>>>> @@ -167,9 +167,6 @@
>>>>>>>>>>>>    *
>>>>>>>>>>>>    * <p>For more information on the <code>Document</code> 
>>>>>>>>>>>> class, see
>>>>>>>>>>>>    * <a 
>>>>>>>>>>>> href="http://www.oracle.com/technetwork/java/javase/tech/articles-jsp-139072.html">The 
>>>>>>>>>>>> Swing Connection</a>
>>>>>>>>>>>> *- * and most particularly the article,**
>>>>>>>>>>>> **- * <a 
>>>>>>>>>>>> href="http://java.sun.com/products/jfc/tsc/articles/text/element_interface">**
>>>>>>>>>>>> **- * The Element Interface</a>.*
>>>>>>>>>>>>    *
>>>>>>>>>>>>    * @author  Timothy Prinzing
>>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>> Regards
>>>>>>>>>>>>
>>>>>>>>>>>> Prasanta
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>
>>>>>>>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/swing-dev/attachments/20191211/1de4dda2/attachment-0001.htm>


More information about the swing-dev mailing list