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

Philip Race philip.race at oracle.com
Mon Dec 9 17:30:15 UTC 2019 

 >

  * ||
    <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/20191209/3a9cdbf7/attachment-0001.htm>

More information about the swing-dev mailing list