DatagramPacket.java, [...]: re-indented documentation.

2002-09-02  Michael Koch  <konqueror@gmx.de>

	* java/net/DatagramPacket.java, java/net/MulticsstSocket.java:
	re-indented documentation.

From-SVN: r56739

3 files changed, 263 insertions, 259 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index 3e31ea2..0fe3d27 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,3 +1,8 @@
+2002-09-02  Michael Koch  <konqueror@gmx.de>
+
+	* java/net/DatagramPacket.java, java/net/MulticsstSocket.java:
+	re-indented documentation.
+
 2002-08-30  Jesse Rosenstock  <jmr@ugcs.caltech.edu>
 
 	* java/util/Calendar.java (getTimeInMillis, getTimeInMillis): Now
diff --git a/libjava/java/net/DatagramPacket.java b/libjava/java/net/DatagramPacket.java
index d136f84..52e3ff2 100644
--- a/libjava/java/net/DatagramPacket.java
+++ b/libjava/java/net/DatagramPacket.java
@@ -44,67 +44,66 @@ package java.net;
  */
 
 /**
-  * This class models a packet of data that is to be sent across the network
-  * using a connectionless protocol such as UDP.  It contains the data
-  * to be send, as well as the destination address and port.  Note that
-  * datagram packets can arrive in any order and are not guaranteed to be
-  * delivered at all.
-  * <p>
-  * This class can also be used for receiving data from the network.
-  * <p>
-  * Note that for all method below where the buffer length passed by the
-  * caller cannot exceed the actually length of the byte array passed as
-  * the buffer, if this condition is not true, then the method silently
-  * reduces the length value to maximum allowable value.
-  *
-  * Written using on-line Java Platform 1.2 API Specification, as well
-  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
-  * Status:  Believed complete and correct.
-  *
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @author Aarom M. Renn (arenn@urbanophile.com) (Documentation comments)
-  * @date April 28, 1999.
-  */
-
+ * This class models a packet of data that is to be sent across the network
+ * using a connectionless protocol such as UDP.  It contains the data
+ * to be send, as well as the destination address and port.  Note that
+ * datagram packets can arrive in any order and are not guaranteed to be
+ * delivered at all.
+ * <p>
+ * This class can also be used for receiving data from the network.
+ * <p>
+ * Note that for all method below where the buffer length passed by the
+ * caller cannot exceed the actually length of the byte array passed as
+ * the buffer, if this condition is not true, then the method silently
+ * reduces the length value to maximum allowable value.
+ *
+ * Written using on-line Java Platform 1.2 API Specification, as well
+ * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
+ * Status:  Believed complete and correct.
+ *
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @author Aarom M. Renn (arenn@urbanophile.com) (Documentation comments)
+ * @date April 28, 1999.
+ */
 public final class DatagramPacket
 {
-/**
-  * The data buffer to send
-  */
+  /**
+   * The data buffer to send
+   */
   private byte[] buffer;
 
-/**
-  * This is the offset into the buffer to start sending from or receiving to.
-  */
+  /**
+   * This is the offset into the buffer to start sending from or receiving to.
+   */
   private int offset;
 
-/**
-  * The length of the data buffer to send
-  */
+  /**
+   * The length of the data buffer to send
+   */
   private int length;
 
-/**
-  * The address to which the packet should be sent or from which it
-  * was received
-  */
+  /**
+   * The address to which the packet should be sent or from which it
+   * was received
+   */
   private InetAddress address;
 
-/**
-  * The port to which the packet should be sent or from which it was
-  * was received.
-  */
+  /**
+   * The port to which the packet should be sent or from which it was
+   * was received.
+   */
   private int port;
 
-/**
-  * This method initializes a new instance of <code>DatagramPacket</code>
-  * which has the specified buffer, offset, and length.
-  *
-  * @param buf The buffer for holding the incoming datagram.
-  * @param offset The offset into the buffer to start writing.
-  * @param length The maximum number of bytes to read.
-  *
-  * @since 1.2
-  */
+  /**
+   * This method initializes a new instance of <code>DatagramPacket</code>
+   * which has the specified buffer, offset, and length.
+   *
+   * @param buf The buffer for holding the incoming datagram.
+   * @param offset The offset into the buffer to start writing.
+   * @param length The maximum number of bytes to read.
+   *
+   * @since 1.2
+   */
   public DatagramPacket(byte[] buf, int offset, int length)
   {
     if (buf == null)
@@ -124,30 +123,30 @@ public final class DatagramPacket
     this.port = -1;
   }
 
-/**
-  * Initializes a new instance of <code>DatagramPacket</code> for
-  * receiving packets from the network.
-  *
-  * @param buf A buffer for storing the returned packet data
-  * @param length The length of the buffer (must be <= buf.length)
-  */
+  /**
+   * Initializes a new instance of <code>DatagramPacket</code> for
+   * receiving packets from the network.
+   *
+   * @param buf A buffer for storing the returned packet data
+   * @param length The length of the buffer (must be <= buf.length)
+   */
   public DatagramPacket(byte[] buf, int length)
   {
     this(buf, 0, length);
   }
 
-/**
-  * Initializes a new instance of <code>DatagramPacket</code> for
-  * transmitting packets across the network.
-  *
-  * @param buf A buffer containing the data to send
-  * @param offset The offset into the buffer to start writing from.
-  * @param len The length of the buffer (must be <= buf.length)
-  * @param addr The address to send to
-  * @param port The port to send to
-  *
-  * @since 1.2
-  */
+  /**
+   * Initializes a new instance of <code>DatagramPacket</code> for
+   * transmitting packets across the network.
+   *
+   * @param buf A buffer containing the data to send
+   * @param offset The offset into the buffer to start writing from.
+   * @param len The length of the buffer (must be <= buf.length)
+   * @param addr The address to send to
+   * @param port The port to send to
+   *
+   * @since 1.2
+   */
   public DatagramPacket(byte[] buf, int offset, int length,
 	InetAddress address, int port)
   {
@@ -172,15 +171,15 @@ public final class DatagramPacket
     this.port = port;
   }
 
-/**
-  * Initializes a new instance of <code>DatagramPacket</code> for
-  * transmitting packets across the network.
-  *
-  * @param buf A buffer containing the data to send
-  * @param length The length of the buffer (must be <= buf.length)
-  * @param address The address to send to
-  * @param port The port to send to
-  */
+  /**
+   * Initializes a new instance of <code>DatagramPacket</code> for
+   * transmitting packets across the network.
+   *
+   * @param buf A buffer containing the data to send
+   * @param length The length of the buffer (must be <= buf.length)
+   * @param address The address to send to
+   * @param port The port to send to
+   */
   public DatagramPacket(byte[] buf, int length, InetAddress address, int port)
   {
     this(buf, 0, length, address, port);
@@ -225,74 +224,74 @@ public final class DatagramPacket
          ((InetSocketAddress)address).getPort());
   }
 
-/**
-  * Returns the address that this packet is being sent to or, if it was used
-  * to receive a packet, the address that is was received from.  If the
-  * constructor that doesn not take an address was used to create this object
-  * and no packet was actually read into this object, then this method
-  * returns <code>null</code>.
-  *
-  * @return The address for this packet.
-  */
+  /**
+   * Returns the address that this packet is being sent to or, if it was used
+   * to receive a packet, the address that is was received from.  If the
+   * constructor that doesn not take an address was used to create this object
+   * and no packet was actually read into this object, then this method
+   * returns <code>null</code>.
+   *
+   * @return The address for this packet.
+   */
   public synchronized InetAddress getAddress()
   {
     return address;
   }
 
-/**
-  * Returns the port number this packet is being sent to or, if it was used
-  * to receive a packet, the port that it was received from. If the
-  * constructor that doesn not take an address was used to create this object
-  * and no packet was actually read into this object, then this method
-  * will return 0.
-  *
-  * @return The port number for this packet
-  */
+  /**
+   * Returns the port number this packet is being sent to or, if it was used
+   * to receive a packet, the port that it was received from. If the
+   * constructor that doesn not take an address was used to create this object
+   * and no packet was actually read into this object, then this method
+   * will return 0.
+   *
+   * @return The port number for this packet
+   */
   public synchronized int getPort()
   {
     return port;
   }
 
-/**
-  * Returns the data buffer for this packet
-  *
-  * @return This packet's data buffer
-  */
+  /**
+   * Returns the data buffer for this packet
+   *
+   * @return This packet's data buffer
+   */
   public synchronized byte[] getData()
   {
     return buffer;
   }
 
-/**
-  * This method returns the current offset value into the data buffer
-  * where data will be sent from.
-  *
-  * @return The buffer offset.
-  *
-  * @since 1.2
-  */
+  /**
+   * This method returns the current offset value into the data buffer
+   * where data will be sent from.
+   *
+   * @return The buffer offset.
+   *
+   * @since 1.2
+   */
   public synchronized int getOffset()
   {
     return offset;
   }
 
-/**
-  * Returns the length of the data in the buffer
-  *
-  * @return The length of the data
-  */
+  /**
+   * Returns the length of the data in the buffer
+   *
+   * @return The length of the data
+   */
   public synchronized int getLength()
   {
     return length;
   }
 
-/**
-  * This sets the address to which the data packet will be transmitted.
-  *
-  * @param addr The destination address
-  *
-  * @since 1.1
-  */
+  /**
+   * This sets the address to which the data packet will be transmitted.
+   *
+   * @param addr The destination address
+   *
+   * @since 1.1
+   */
   public synchronized void setAddress(InetAddress iaddr)
   {
     if (iaddr == null)
@@ -301,13 +300,13 @@ public final class DatagramPacket
     address = iaddr;
   }
 
-/**
-  * This sets the port to which the data packet will be transmitted.
-  *
-  * @param port The destination port
-  *
-  * @since 1.1
-  */
+  /**
+   * This sets the port to which the data packet will be transmitted.
+   *
+   * @param port The destination port
+   *
+   * @since 1.1
+   */
   public synchronized void setPort(int iport)
   {
     if (iport < 0 || iport > 65535)
@@ -348,13 +347,13 @@ public final class DatagramPacket
     return new InetSocketAddress (address, port);
   }
 
-/**
-  * Sets the data buffer for this packet.
-  *
-  * @param buf The new buffer for this packet
-  *
-  * @since 1.1
-  */
+  /**
+   * Sets the data buffer for this packet.
+   *
+   * @param buf The new buffer for this packet
+   *
+   * @since 1.1
+   */
   public synchronized void setData(byte[] buf)
   {
     // This form of setData requires setLength to be called separately
@@ -365,15 +364,15 @@ public final class DatagramPacket
     buffer = buf;
   }
 
-/**
-  * This method sets the data buffer for the packet.
-  *
-  * @param buf The byte array containing the data for this packet.
-  * @param offset The offset into the buffer to start reading data from.
-  * @param length The number of bytes of data in the buffer.
-  *
-  * @since 1.2
-  */
+  /**
+   * This method sets the data buffer for the packet.
+   *
+   * @param buf The byte array containing the data for this packet.
+   * @param offset The offset into the buffer to start reading data from.
+   * @param length The number of bytes of data in the buffer.
+   *
+   * @since 1.2
+   */
   public synchronized void setData(byte[] buf, int offset, int length)
   {
     // This form of setData must be used if offset is to be changed.
@@ -393,13 +392,13 @@ public final class DatagramPacket
     this.length = length;
   }
 
-/**
-  * Sets the length of the data in the buffer. 
-  *
-  * @param length The new length.  (Where len <= buf.length)
-  *
-  * @since 1.1
-  */
+  /**
+   * Sets the length of the data in the buffer. 
+   *
+   * @param length The new length.  (Where len <= buf.length)
+   *
+   * @since 1.1
+   */
   public synchronized void setLength(int length)
   {
     if (length < 0)
diff --git a/libjava/java/net/MulticastSocket.java b/libjava/java/net/MulticastSocket.java
index 7381a86..54ed5c1 100644
--- a/libjava/java/net/MulticastSocket.java
+++ b/libjava/java/net/MulticastSocket.java
@@ -39,82 +39,82 @@ package java.net;
 
 import java.io.IOException;
 
-/*
+/**
  * Written using on-line Java Platform 1.2 API Specification, as well
  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
  * Status:  Believed complete and correct.
  */
 
 /**
-  * This class models a multicast UDP socket.  A multicast address is a
-  * class D internet address (one whose most significant bits are 1110).  
-  * A multicast group consists of a multicast address and a well known
-  * port number.  All members of the group listening on that address and
-  * port will receive all the broadcasts to the group.
-  * <p>
-  * Please note that applets are not allowed to use multicast sockets 
-  * 
-  * Written using on-line Java Platform 1.2 API Specification, as well
-  * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
-  * Status:  Believed complete and correct.
-  *
-  * @author Warren Levy <warrenl@cygnus.com>
-  * @author Aaron M. Renn (arenn@urbanophile.com) (Documentation comments)
-  * @since 1.1
-  * @date May 18, 1999.
-  */
+ * This class models a multicast UDP socket.  A multicast address is a
+ * class D internet address (one whose most significant bits are 1110).  
+ * A multicast group consists of a multicast address and a well known
+ * port number.  All members of the group listening on that address and
+ * port will receive all the broadcasts to the group.
+ * <p>
+ * Please note that applets are not allowed to use multicast sockets 
+ * 
+ * Written using on-line Java Platform 1.2 API Specification, as well
+ * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
+ * Status:  Believed complete and correct.
+ *
+ * @author Warren Levy <warrenl@cygnus.com>
+ * @author Aaron M. Renn (arenn@urbanophile.com) (Documentation comments)
+ * @since 1.1
+ * @date May 18, 1999.
+ */
 public class MulticastSocket extends DatagramSocket
 {
   // FIXME: the local addr bound to the multicast socket can be reused;
   // unlike unicast sockets.  It binds to any available network interface.
   // See p.1159 JCL book.
 
-/**
-  * Create a MulticastSocket that this not bound to any address
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Create a MulticastSocket that this not bound to any address
+   *
+   * @exception IOException If an error occurs
+   */
   public MulticastSocket() throws IOException
   {
     super(0, null);
   }
 
-/**
-  * Create a multicast socket bound to the specified port
-  *
-  * @param The port to bind to
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Create a multicast socket bound to the specified port
+   *
+   * @param port The port to bind to
+   *
+   * @exception IOException If an error occurs
+   */
   public MulticastSocket(int port) throws IOException
   {
     super(port, null);
   }
 
-/**
-  * Returns the interface being used for multicast packets
-  * 
-  * @return The multicast interface
-  *
-  * @exception SocketException If an error occurs
-  */
+  /**
+   * Returns the interface being used for multicast packets
+   * 
+   * @return The multicast interface
+   *
+   * @exception SocketException If an error occurs
+   */
   public InetAddress getInterface() throws SocketException
   {
     // FIXME: Is it possible that an InetAddress wasn't returned from getOption?
     return (InetAddress) impl.getOption(SocketOptions.IP_MULTICAST_IF);
   }
 
-/**
-  * Returns the current value of the "Time to Live" option.  This is the
-  * number of hops a packet can make before it "expires".   This method id
-  * deprecated.  Use <code>getTimeToLive</code> instead.
-  * 
-  * @return The TTL value
-  *
-  * @exception IOException If an error occurs
-  *
-  * @deprecated Replaced by getTimeToLive() in Java 1.2
-  */
+  /**
+   * Returns the current value of the "Time to Live" option.  This is the
+   * number of hops a packet can make before it "expires".   This method id
+   * deprecated.  Use <code>getTimeToLive</code> instead.
+   * 
+   * @return The TTL value
+   *
+   * @exception IOException If an error occurs
+   *
+   * @deprecated 1.2 Replaced by getTimeToLive()
+   */
   public byte getTTL() throws IOException
   {
     // Use getTTL here rather than getTimeToLive in case we're using an impl
@@ -123,43 +123,43 @@ public class MulticastSocket extends DatagramSocket
     return impl.getTTL();
   }
 
-/**
-  * Returns the current value of the "Time to Live" option.  This is the
-  * number of hops a packet can make before it "expires". 
-  * 
-  * @return The TTL value
-  *
-  * @exception IOException If an error occurs
-  *
-  * @since Java 1.2
-  */
+  /**
+   * Returns the current value of the "Time to Live" option.  This is the
+   * number of hops a packet can make before it "expires". 
+   * 
+   * @return The TTL value
+   *
+   * @exception IOException If an error occurs
+   *
+   * @since 1.2
+   */
   public int getTimeToLive() throws IOException
   {
     return impl.getTimeToLive();
   }
 
-/**
-  * Sets the interface to use for multicast packets.
-  *
-  * @param addr The new interface to use
-  *
-  * @exception SocketException If an error occurs
-  */
+   /**
+    * Sets the interface to use for sending multicast packets.
+    *
+    * @param inf The new interface to use
+    *
+    * @exception SocketException If an error occurs
+    */
   public void setInterface(InetAddress inf) throws SocketException
   {
     impl.setOption(SocketOptions.IP_MULTICAST_IF, inf);
   }
 
-/**
-  * Sets the "Time to Live" value for a socket.  The value must be between
-  * 1 and 255.
-  *
-  * @param ttl The new TTL value
-  *
-  * @exception IOException If an error occurs
-  *
-  * @deprecated Replaced by <code>setTimeToLive</code> in Java 1.2
-  */
+  /**
+   * Sets the "Time to Live" value for a socket.  The value must be between
+   * 1 and 255.
+   *
+   * @param ttl The new TTL value
+   *
+   * @exception IOException If an error occurs
+   *
+   * @deprecated 1.2 Replaced by <code>setTimeToLive</code>
+   */
   public void setTTL(byte ttl) throws IOException
   {
     // Use setTTL here rather than setTimeToLive in case we're using an impl
@@ -168,16 +168,16 @@ public class MulticastSocket extends DatagramSocket
     impl.setTTL(ttl);
   }
 
-/**
-  * Sets the "Time to Live" value for a socket.  The value must be between
-  * 1 and 255.  
-  *
-  * @param ttl The new TTL value
-  *
-  * @exception IOException If an error occurs
-  * 
-  * @since Java 1.2
-  */
+  /**
+   * Sets the "Time to Live" value for a socket.  The value must be between
+   * 1 and 255.  
+   *
+   * @param ttl The new TTL value
+   *
+   * @exception IOException If an error occurs
+   * 
+   * @since 1.2
+   */
   public void setTimeToLive(int ttl) throws IOException
   {
     if (ttl <= 0 || ttl > 255)
@@ -186,13 +186,13 @@ public class MulticastSocket extends DatagramSocket
     impl.setTimeToLive(ttl);
   }
 
-/**
-  * Joins the specified mulitcast group.
-  *
-  * @param addr The address of the group to join
-  * 
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Joins the specified mulitcast group.
+   *
+   * @param addr The address of the group to join
+   * 
+   * @exception IOException If an error occurs
+   */
   public void joinGroup(InetAddress mcastaddr) throws IOException
   {
     if (! mcastaddr.isMulticastAddress())
@@ -205,13 +205,13 @@ public class MulticastSocket extends DatagramSocket
     impl.join(mcastaddr);
   }
 
-/**
-  * Leaves the specified multicast group
-  *
-  * @param addr The address of the group to leave
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Leaves the specified multicast group
+   *
+   * @param addr The address of the group to leave
+   *
+   * @exception IOException If an error occurs
+   */
   public void leaveGroup(InetAddress mcastaddr) throws IOException
   {
     if (! mcastaddr.isMulticastAddress())
@@ -224,16 +224,16 @@ public class MulticastSocket extends DatagramSocket
     impl.leave(mcastaddr);
   }
 
-/**
-  * Sends a packet of data to a multicast address with a TTL that is
-  * different from the default TTL on this socket.  The default TTL for
-  * the socket is not changed.
-  *
-  * @param packet The packet of data to send
-  * @param ttl The TTL for this packet
-  *
-  * @exception IOException If an error occurs
-  */
+  /**
+   * Sends a packet of data to a multicast address with a TTL that is
+   * different from the default TTL on this socket.  The default TTL for
+   * the socket is not changed.
+   *
+   * @param packet The packet of data to send
+   * @param ttl The TTL for this packet
+   *
+   * @exception IOException If an error occurs
+   */
   public synchronized void send(DatagramPacket p, byte ttl) throws IOException
   {
     SecurityManager s = System.getSecurityManager();