javadoc fixes

Change-Id: I3b4fc2d99f42b2413a535fb411b9c19bdd186ad8

@@ -85,7 +85,7 @@ public class IOLoopTestClient {
         System.exit(0);
     }
 
-    /**
+    /*
      * Starts a standalone IO loop test client.
      *
      * @param args command-line arguments

@@ -85,7 +85,7 @@ public class IOLoopTestServer {
         System.exit(0);
     }
 
-    /**
+    /*
      * Starts a standalone IO loop test server.
      *
      * @param args command-line arguments

@@ -92,6 +92,7 @@ public abstract class AbstractShellCommand extends OsgiCommandSupport {
     /**
      * Produces a JSON object from the specified key/value annotations.
      *
+     * @param mapper ObjectMapper to use while converting to JSON
      * @param annotations key/value annotations
      * @return JSON object
      */

@@ -44,6 +44,7 @@ public abstract class ConnectivityIntentCommand extends AbstractShellCommand {
     /**
      * Constructs a traffic selector based on the command line arguments
      * presented to the command.
+     * @return traffic selector
      */
     protected TrafficSelector buildTrafficSelector() {
         TrafficSelector.Builder selectorBuilder = DefaultTrafficSelector.builder();

@@ -141,7 +141,8 @@ public class FlowsListCommand extends AbstractShellCommand {
     /**
      * Returns the list of devices sorted using the device ID URIs.
      *
-     * @param service device service
+     * @param deviceService device service
+     * @param service flow rule service
      * @return sorted device list
      */
     protected Map<Device, List<FlowEntry>> getSortedFlows(DeviceService deviceService,
@@ -175,7 +176,8 @@ public class FlowsListCommand extends AbstractShellCommand {
      * Prints flows.
      *
      * @param d     the device
-     * @param flows the set of flows for that device.
+     * @param flows the set of flows for that device
+     * @param coreService core system service
      */
     protected void printFlows(Device d, List<FlowEntry> flows,
                               CoreService coreService) {

@@ -54,6 +54,7 @@ public class DefaultControllerNode implements ControllerNode {
      *
      * @param id instance identifier
      * @param ip instance IP address
+     * @param tcpPort TCP port
      */
     public DefaultControllerNode(NodeId id, IpAddress ip, int tcpPort) {
         this.id = id;

@@ -54,6 +54,7 @@ public class DefaultDevice extends AbstractElement implements Device {
      * @param hwVersion    device HW version
      * @param swVersion    device SW version
      * @param serialNumber device serial number
+     * @param chassisId    chasis id
      * @param annotations optional key/value annotations
      */
     public DefaultDevice(ProviderId providerId, DeviceId id, Type type,

@@ -48,6 +48,7 @@ public final class DeviceId extends ElementId {
      * Creates a device id using the supplied URI.
      *
      * @param uri device URI
+     * @return DeviceId
      */
     public static DeviceId deviceId(URI uri) {
         return new DeviceId(uri);
@@ -57,6 +58,7 @@ public final class DeviceId extends ElementId {
      * Creates a device id using the supplied URI string.
      *
      * @param string device URI string
+     * @return DeviceId
      */
     public static DeviceId deviceId(String string) {
         return deviceId(URI.create(string));

@@ -47,6 +47,7 @@ public class DefaultDeviceDescription extends AbstractDescription
      * @param hwVersion    device HW version
      * @param swVersion    device SW version
      * @param serialNumber device serial number
+     * @param chassis      chasis id
      * @param annotations  optional key/value annotations map
      */
     public DefaultDeviceDescription(URI uri, Type type, String manufacturer,

@@ -32,6 +32,7 @@ public interface DeviceProviderService extends ProviderService<DeviceProvider> {
     /**
      * Signals the core that a device has connected or has been detected somehow.
      *
+     * @param deviceId device identifier
      * @param deviceDescription information about network device
      */
     void deviceConnected(DeviceId deviceId, DeviceDescription deviceDescription);
@@ -65,7 +66,7 @@ public interface DeviceProviderService extends ProviderService<DeviceProvider> {
      *
      * @param deviceId identity of the device
      * @param requested mastership role that was requested by the node
-     * @param replied mastership role the switch accepted
+     * @param response mastership role the switch accepted
      */
     void receivedRoleReply(DeviceId deviceId, MastershipRole requested, MastershipRole response);
 

@@ -125,6 +125,7 @@ public interface DeviceStore extends Store<DeviceEvent, DeviceStoreDelegate> {
      * Administratively removes the specified device from the store.
      *
      * @param deviceId device to be removed
+     * @return null if no such device, or was forwarded to remove master
      */
     DeviceEvent removeDevice(DeviceId deviceId);
 }

@@ -99,6 +99,7 @@ public final class DefaultTrafficSelector implements TrafficSelector {
      * Returns a new traffic selector builder primed to produce entities
      * patterned after the supplied selector.
      *
+     * @param selector base selector
      * @return traffic selector builder
      */
     public static TrafficSelector.Builder builder(TrafficSelector selector) {

@@ -63,6 +63,7 @@ public final class DefaultTrafficTreatment implements TrafficTreatment {
      * Returns a new traffic treatment builder primed to produce entities
      * patterned after the supplied treatment.
      *
+     * @param treatment base treatment
      * @return traffic treatment builder
      */
     public static TrafficTreatment.Builder builder(TrafficTreatment treatment) {

@@ -48,6 +48,7 @@ public interface FlowRuleProvider extends Provider {
     /**
      * Removes rules by their id.
      * @param id the id to remove
+     * @param flowRules one or more flow rules
      */
     void removeRulesById(ApplicationId id, FlowRule... flowRules);
 

@@ -35,6 +35,7 @@ public interface FlowRuleProviderService extends ProviderService<FlowRuleProvide
      * Pushes the collection of flow entries currently applied on the given
      * device.
      *
+     * @param deviceId device identifier
      * @param flowEntries collection of flow rules
      */
     void pushFlowMetrics(DeviceId deviceId, Iterable<FlowEntry> flowEntries);

@@ -86,6 +86,7 @@ public interface FlowRuleService {
     /**
      * Applies a batch operation of FlowRules.
      *
+     * @param batch batch operation to apply
      * @return future indicating the state of the batch operation
      */
     Future<CompletedBatchOperation> applyBatch(FlowRuleBatchOperation batch);

@@ -137,14 +137,14 @@ public interface TrafficSelector {
 
         /**
          * Matches an optical signal ID or lambda.
-         * @param lambda
+         * @param lambda lamda
          * @return a selection builder
          */
         public Builder matchLambda(Short lambda);
 
         /**
          * Matches an optical Signal Type.
-         * @param signalType
+         * @param signalType signalType
          * @return a selection builder
          */
         public Builder matchOpticalSignalType(Short signalType);

@@ -131,7 +131,7 @@ public final class Criteria {
     /**
      * Creates a match on TCP source port field using the specified value.
      *
-     * @param tcpPort
+     * @param tcpPort TCP source port
      * @return match criterion
      */
     public static Criterion matchTcpSrc(Short tcpPort) {
@@ -141,7 +141,7 @@ public final class Criteria {
     /**
      * Creates a match on TCP destination port field using the specified value.
      *
-     * @param tcpPort
+     * @param tcpPort TCP destination port
      * @return match criterion
      */
     public static Criterion matchTcpDst(Short tcpPort) {
@@ -151,7 +151,7 @@ public final class Criteria {
     /**
      * Creates a match on lambda field using the specified value.
      *
-     * @param lambda
+     * @param lambda lamda to match on
      * @return match criterion
      */
     public static Criterion matchLambda(Short lambda) {
@@ -161,7 +161,7 @@ public final class Criteria {
     /**
      * Creates a match on lambda field using the specified value.
      *
-     * @param sigType
+     * @param sigType signame type
      * @return match criterion
      */
     public static Criterion matchOpticalSignalType(Short sigType) {

@@ -91,6 +91,7 @@ public abstract class Intent implements BatchOperationTarget {
      * Produces an intent identifier backed by hash-like fingerprint for the
      * specified class of intent and its constituent fields.
      *
+     * @param intentClass Class of the intent
      * @param fields intent fields
      * @return intent identifier
      */

@@ -27,6 +27,7 @@ public interface IntentInstaller<T extends Intent> {
      * Installs the specified intent to the environment.
      *
      * @param intent intent to be installed
+     * @return FlowRule operations to install
      * @throws IntentException if issues are encountered while installing the intent
      */
     List<FlowRuleBatchOperation> install(T intent);
@@ -35,6 +36,7 @@ public interface IntentInstaller<T extends Intent> {
      * Uninstalls the specified intent from the environment.
      *
      * @param intent intent to be uninstalled
+     * @return FlowRule operations to uninstall
      * @throws IntentException if issues are encountered while uninstalling the intent
      */
     List<FlowRuleBatchOperation> uninstall(T intent);

@@ -59,6 +59,7 @@ public interface IntentService {
      * affected at later time.
      * </p>
      * @param operations batch of intent operations
+     * @return Future to get execution result
      */
     Future<IntentOperations> execute(IntentOperations operations);
 

@@ -42,6 +42,7 @@ public class PathIntent extends ConnectivityIntent {
      * @param selector  traffic selector
      * @param treatment treatment
      * @param path      traversed links
+     * @param resourceRequests link resource request
      * @throws NullPointerException {@code path} is null
      */
     public PathIntent(ApplicationId appId, TrafficSelector selector,

@@ -46,6 +46,7 @@ public class PointToPointIntentWithBandwidthConstraint extends ConnectivityInten
      * @param treatment    treatment
      * @param ingressPoint ingress port
      * @param egressPoint  egress port
+     * @param bandwidthResourceRequest bandwidth resource request
      * @throws NullPointerException if {@code ingressPoint} or {@code egressPoints} is null.
      */
     public PointToPointIntentWithBandwidthConstraint(ApplicationId appId, TrafficSelector selector,

@@ -34,7 +34,7 @@ public interface StatisticStore {
 
     /**
      * Remove entries associated with this rule.
-     a @param rule {@link org.onlab.onos.net.flow.FlowRule}
+     * @param rule {@link org.onlab.onos.net.flow.FlowRule}
      */
     void removeFromStatistics(FlowRule rule);
 

@@ -43,6 +43,7 @@ public interface PathService {
      *
      * @param src source element
      * @param dst destination element
+     * @param weight edge-weight entity
      * @return set of all shortest paths between the two element
      */
     Set<Path> getPaths(ElementId src, ElementId dst, LinkWeight weight);

@@ -103,6 +103,7 @@ public interface TopologyService {
      * @param topology topology descriptor
      * @param src      source device
      * @param dst      destination device
+     * @param weight   edge-weight entity
      * @return set of all shortest paths between the two devices
      */
     Set<Path> getPaths(Topology topology, DeviceId src, DeviceId dst,

@@ -33,6 +33,7 @@ public interface ClusterCommunicationService {
      *
      * @param message  message to send
      * @return true if the message was sent successfully to all nodes; false otherwise.
+     * @throws IOException when I/O exception of some sort has occurred
      */
     boolean broadcast(ClusterMessage message) throws IOException;
 
@@ -42,6 +43,7 @@ public interface ClusterCommunicationService {
      * @param message  message to send
      * @param toNodeId node identifier
      * @return true if the message was sent successfully; false otherwise.
+     * @throws IOException when I/O exception of some sort has occurred
      */
     boolean unicast(ClusterMessage message, NodeId toNodeId) throws IOException;
 
@@ -49,7 +51,9 @@ public interface ClusterCommunicationService {
      * Multicast a message to a set of controller nodes.
      *
      * @param message  message to send
+     * @param nodeIds  recipient node identifiers
      * @return true if the message was sent successfully to all nodes in the group; false otherwise.
+     * @throws IOException when I/O exception of some sort has occurred
      */
     boolean multicast(ClusterMessage message, Set<NodeId> nodeIds) throws IOException;
 
@@ -58,7 +62,7 @@ public interface ClusterCommunicationService {
      * @param message message to send
      * @param toNodeId recipient node identifier
      * @return reply future.
-     * @throws IOException
+     * @throws IOException when I/O exception of some sort has occurred
      */
     ListenableFuture<byte[]> sendAndReceive(ClusterMessage message, NodeId toNodeId) throws IOException;
 

@@ -32,7 +32,9 @@ public class ClusterMessage {
     /**
      * Creates a cluster message.
      *
+     * @param sender  message sender
      * @param subject message subject
+     * @param payload message payload
      */
     public ClusterMessage(NodeId sender, MessageSubject subject, byte[] payload) {
         this.sender = sender;
@@ -71,7 +73,7 @@ public class ClusterMessage {
      * Sends a response to the sender.
      *
      * @param data payload response.
-     * @throws IOException
+     * @throws IOException when I/O exception of some sort has occurred
      */
     public void respond(byte[] data) throws IOException {
         throw new IllegalStateException("One can only repond to message recived from others.");

@@ -48,7 +48,7 @@ public class ClusterDefinitionStore {
         file = new File(filePath);
     }
 
-    /**
+    /*
      * Returns set of the controller nodes, including self.
      *
      * @return set of controller nodes
@@ -67,7 +67,7 @@ public class ClusterDefinitionStore {
         return nodes;
     }
 
-    /**
+    /*
      * Writes the given set of the controller nodes.
      *
      * @param nodes set of controller nodes

@@ -44,6 +44,7 @@ public interface StoreSerializer {
      *
      * @param bytes bytes to be deserialized
      * @return deserialized object
+     * @param <T> decoded type
      */
     public <T> T decode(final byte[] bytes);
 
@@ -52,6 +53,7 @@ public interface StoreSerializer {
      *
      * @param buffer bytes to be deserialized
      * @return deserialized object
+     * @param <T> decoded type
      */
     public <T> T decode(final ByteBuffer buffer);
 }

@@ -26,6 +26,7 @@ public interface OpenFlowEventListener {
     /**
      * Handles the message event.
      *
+     * @param dpid switch data path identifier
      * @param msg the message
      */
     public void handleMessage(Dpid dpid, OFMessage msg);

@@ -31,6 +31,7 @@ public interface OpenFlowPacketContext {
     /**
      * Blocks further responses (ie. send() calls) on this
      * packet in event.
+     * @return true if blocks
      */
     public boolean block();
 

@@ -133,7 +133,7 @@ public interface OpenFlowSwitch {
      * @param requested the role requested by the controller
      * @param response the role set at the device
      */
-    public void returnRoleReply(RoleState requested, RoleState reponse);
+    public void returnRoleReply(RoleState requested, RoleState response);
 
     /**
      * Indicates if this switch is optical.

@@ -51,7 +51,8 @@ public interface OpenFlowSwitchListener {
      * Notify that a role imposed on a switch failed to take hold.
      *
      * @param dpid the switch that failed role assertion
-     * @param role the role imposed by the controller
+     * @param requested the role controller requested
+     * @param response role reply from the switch
      */
     public void receivedRoleReply(Dpid dpid, RoleState requested, RoleState response);
 }

@@ -95,7 +95,8 @@ public interface OpenFlowAgent {
      * Notifies the controller that role assertion has failed.
      *
      * @param dpid the switch that failed role assertion
-     * @param role the failed role
+     * @param requested the role controller requested
+     * @param response role reply from the switch
      */
     public void returnRoleReply(Dpid dpid, RoleState requested, RoleState response);
 }

@@ -58,8 +58,9 @@ public interface RoleHandler {
      * OF1.3 switches, because Role.EQUAL is well defined and we can simulate
      * SLAVE behavior by using ASYNC messages.
      *
-     * @param role
-     * @throws IOException
+     * @param role role to request
+     * @param exp expectation
+     * @throws IOException when I/O exception of some sort has occurred
      * @return false if and only if the switch does not support role-request
      * messages, according to the switch driver; true otherwise.
      */
@@ -70,7 +71,7 @@ public interface RoleHandler {
      * Extract the role information from an OF1.3 Role Reply Message.
      * @param rrmsg role reply message
      * @return RoleReplyInfo object
-     * @throws SwitchStateException
+     * @throws SwitchStateException If unknown role encountered
      */
     public RoleReplyInfo extractOFRoleReply(OFRoleReply rrmsg)
             throws SwitchStateException;
@@ -89,6 +90,7 @@ public interface RoleHandler {
      *
      * @param rri information about role-reply in format that
      *                      controller can understand.
+     * @return result comparing expected and received reply
      * @throws SwitchStateException if no request is pending
      */
     public RoleRecvStatus deliverRoleReply(RoleReplyInfo rri)
@@ -102,6 +104,9 @@ public interface RoleHandler {
      * Note: since we only keep the last pending request we might get
      * error messages for earlier role requests that we won't be able
      * to handle
+     * @param error error message
+     * @return result comparing expected and received reply
+     * @throws SwitchStateException if switch did not support requested role
      */
     public RoleRecvStatus deliverError(OFErrorMsg error)
             throws SwitchStateException;

@@ -160,6 +160,7 @@ public class Controller {
 
     /**
      * Initialize internal data structures.
+     * @param configParams configuration parameters
      */
     public void init(Map<String, String> configParams) {
         // These data structures are initialized here because other
@@ -192,7 +193,9 @@ public class Controller {
 
     /**
      * Forward to the driver-manager to get an IOFSwitch instance.
-     * @param desc
+     * @param dpid data path id
+     * @param desc switch description
+     * @param ofv OpenFlow version
      * @return switch instance
      */
     protected OpenFlowSwitchDriver getOFSwitchInstance(long dpid,

@@ -90,7 +90,9 @@ public class LinkDiscovery implements TimerTask {
      * Starts the the timer for the discovery process.
      *
      * @param device        the physical switch
+     * @param pktService    packet service
      * @param masterService mastership service
+     * @param providerService link provider service
      * @param useBDDP       flag to also use BDDP for discovery
      */
     public LinkDiscovery(Device device, PacketService pktService,
@@ -201,6 +203,8 @@ public class LinkDiscovery implements TimerTask {
     /**
      * Handles an incoming LLDP packet. Creates link in topology and sends ACK
      * to port where LLDP originated.
+     * @param context packet context
+     * @return true if handled
      */
     public boolean handleLLDP(PacketContext context) {
         Ethernet eth = context.inPacket().parsed();

@@ -87,7 +87,7 @@ public class LinkDiscovery implements TimerTask {
     protected final Map<Integer, OFPortDesc> ports;
     private Timeout timeout;
 
-    /**
+    /*
      * Instantiates discovery manager for the given physical switch. Creates a
      * generic LLDP packet that will be customized for the port it is sent out on.
      * Starts the the timer for the discovery process.
@@ -281,7 +281,7 @@ public class LinkDiscovery implements TimerTask {
         return "LinkDiscovery " + this.sw.getStringId();
     }
 
-    /**
+    /*
      * Handles an incoming LLDP packet. Creates link in topology and sends ACK
      * to port where LLDP originated.
      */

@@ -38,8 +38,8 @@ implements MutableGraph<V, E> {
     /**
      * Creates a graph comprising of the specified vertexes and edges.
      *
-     * @param vertexes set of graph vertexes
-     * @param edges    set of graph edges
+     * @param vertex   set of graph vertexes
+     * @param edge     set of graph edges
      */
     public MutableAdjacencyListsGraph(Set<V> vertex, Set<E> edge) {
         vertexes.addAll(vertex);

@@ -55,6 +55,7 @@ public class ARP extends BasePacket {
     /**
      * @param hwType
      *            the hardwareType to set
+     * @return this
      */
     public ARP setHardwareType(final short hwType) {
         this.hardwareType = hwType;
@@ -71,6 +72,7 @@ public class ARP extends BasePacket {
     /**
      * @param protoType
      *            the protocolType to set
+     * @return this
      */
     public ARP setProtocolType(final short protoType) {
         this.protocolType = protoType;
@@ -87,6 +89,7 @@ public class ARP extends BasePacket {
     /**
      * @param hwAddressLength
      *            the hardwareAddressLength to set
+     * @return this
      */
     public ARP setHardwareAddressLength(final byte hwAddressLength) {
         this.hardwareAddressLength = hwAddressLength;
@@ -103,6 +106,7 @@ public class ARP extends BasePacket {
     /**
      * @param protoAddressLength
      *            the protocolAddressLength to set
+     * @return this
      */
     public ARP setProtocolAddressLength(final byte protoAddressLength) {
         this.protocolAddressLength = protoAddressLength;
@@ -119,6 +123,7 @@ public class ARP extends BasePacket {
     /**
      * @param op
      *            the opCode to set
+     * @return this
      */
     public ARP setOpCode(final short op) {
         this.opCode = op;
@@ -135,6 +140,7 @@ public class ARP extends BasePacket {
     /**
      * @param senderHWAddress
      *            the senderHardwareAddress to set
+     * @return this
      */
     public ARP setSenderHardwareAddress(final byte[] senderHWAddress) {
         this.senderHardwareAddress = senderHWAddress;
@@ -151,6 +157,7 @@ public class ARP extends BasePacket {
     /**
      * @param senderProtoAddress
      *            the senderProtocolAddress to set
+     * @return this
      */
     public ARP setSenderProtocolAddress(final byte[] senderProtoAddress) {
         this.senderProtocolAddress = senderProtoAddress;
@@ -173,6 +180,7 @@ public class ARP extends BasePacket {
     /**
      * @param targetHWAddress
      *            the targetHardwareAddress to set
+     * @return this
      */
     public ARP setTargetHardwareAddress(final byte[] targetHWAddress) {
         this.targetHardwareAddress = targetHWAddress;
@@ -206,6 +214,7 @@ public class ARP extends BasePacket {
     /**
      * @param targetProtoAddress
      *            the targetProtocolAddress to set
+     * @return this
      */
     public ARP setTargetProtocolAddress(final byte[] targetProtoAddress) {
         this.targetProtocolAddress = targetProtoAddress;

@@ -33,7 +33,7 @@ public class Data extends BasePacket {
     }
 
     /**
-     * @param data
+     * @param data the data
      */
     public Data(final byte[] data) {
         this.data = data;
@@ -49,6 +49,7 @@ public class Data extends BasePacket {
     /**
      * @param data
      *            the data to set
+     * @return self
      */
     public Data setData(final byte[] data) {
         this.data = data;

@@ -64,7 +64,7 @@ public interface IPacket {
     /**
      * Deserializes this packet layer and all possible payloads.
      *
-     * @param data
+     * @param data bytes to deserialize
      * @param offset
      *            offset to start deserializing from
      * @param length

@@ -24,7 +24,7 @@ public final class HexString {
     /**
      * Convert a string of bytes to a ':' separated hex string.
      *
-     * @param bytes
+     * @param bytes string of bytes to convert
      * @return "0f:ca:fe:de:ad:be:ef"
      */
     public static String toHexString(final byte[] bytes) {

@@ -29,7 +29,7 @@ public interface MessagingService {
      * @param ep end point to send the message to.
      * @param type type of message.
      * @param payload message payload bytes.
-     * @throws IOException
+     * @throws IOException when I/O exception of some sort has occurred
      */
     public void sendAsync(Endpoint ep, String type, byte[] payload) throws IOException;
 
@@ -39,7 +39,7 @@ public interface MessagingService {
      * @param type type of message.
      * @param payload message payload.
      * @return a response future
-     * @throws IOException
+     * @throws IOException when I/O exception of some sort has occurred
      */
     public ListenableFuture<byte[]> sendAndReceive(Endpoint ep, String type, byte[] payload) throws IOException;
 

@@ -107,6 +107,7 @@ public abstract class IOLoop<M extends Message, S extends MessageStream<M>>
      * Completes connection request pending on the given selection key.
      *
      * @param key selection key holding the pending connect operation.
+     * @throws IOException when I/O exception of some sort has occurred
      */
     protected void connect(SelectionKey key) throws IOException {
         SocketChannel ch = (SocketChannel) key.channel();

@@ -74,6 +74,7 @@ public abstract class SelectorLoop implements Runnable {
 
     /**
      * Indicates that the loop is marked to run.
+     * @return true if the loop is marked to run
      */
     protected boolean isRunning() {
         return state == State.STARTED || state == State.STARTING;

@@ -18,7 +18,7 @@ package org.onlab.thirdparty;
 
 /**
  * Empty class required to get the onlab-thirdparty module to build properly.
- * <p/>
+ *
  * TODO Figure out how to remove this.
  */
 public class OnlabThirdparty {