[Short-circuit API] Add some javadoc.

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BranchFault.java

@@ -8,14 +8,12 @@
 package com.powsybl.shortcircuit;
 
 /**
- * Class to describe the characteristics of the fault to be simulated.
- * Used for elementary short-circuit analysis only.
+ * Class to describe the characteristics of a fault that occurs on a branch and that is to be simulated.
  *
  * @author Anne Tilloy {@literal <anne.tilloy at rte-france.com>}
  */
 public class BranchFault extends AbstractFault {
 
- // Location of the fault in % of the branch length (with side ONE as reference).
  private final double proportionalLocation;
 
  public BranchFault(String id, String elementId, double r, double x, ConnectionType connection, FaultType faultType, double proportionalLocation) {
@@ -25,12 +23,12 @@ public BranchFault(String id, String elementId, double r, double x, ConnectionTy
  }
 
  public BranchFault(String id, String elementId, double r, double x, double proportionalLocation) {
- // Here the elementId is the id of a bus from the bus view.
+ // Here the elementId is the id of a branch.
  this(id, elementId, r, x, ConnectionType.SERIES, FaultType.THREE_PHASE, proportionalLocation);
  }
 
  public BranchFault(String id, String elementId, double proportionalLocation) {
- // Here the elementId is the id of a bus from the bus view.
+ // Here the elementId is the id of a branch.
  this(id, elementId, 0.0, 0.0, ConnectionType.SERIES, FaultType.THREE_PHASE, proportionalLocation);
  }
 
@@ -39,6 +37,10 @@ public Type getType() {
  return Type.BRANCH;
  }
 
+ /**
+ * Get the location of the fault on the branch
+ * @return the location of the fault in % of the branch length (with side ONE as reference).
+ */
  public double getProportionalLocation() {
  return this.proportionalLocation;
  }

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/BusFault.java

@@ -8,8 +8,7 @@
 package com.powsybl.shortcircuit;
 
 /**
- * Class to describe the characteristics of the fault to be simulated.
- * Used for elementary short-circuit analysis only.
+ * Class to describe the characteristics of a fault that occurs on a bus and that is to be simulated.
  *
  * @author Anne Tilloy {@literal <anne.tilloy at rte-france.com>}
  */

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FailedFaultResult.java

@@ -8,6 +8,8 @@
 package com.powsybl.shortcircuit;
 
 /**
+ * A class to represent the result if the analysis has failed.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public class FailedFaultResult extends AbstractFaultResult {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/Fault.java

@@ -21,53 +21,81 @@
 
 /**
  * Interface to describe the characteristics of the fault to be simulated.
- * Used for elementary short-circuit analysis only.
  *
  * @author Anne Tilloy {@literal <anne.tilloy at rte-france.com>}
  */
 public interface Fault {
 
- // Type of fault (use for downcast & serialize/deserialize)
+ /**
+ * Type of fault (use for downcast & serialize/deserialize).
+ */
  enum Type {
  BUS,
  BRANCH
  }
 
- // How the fault impedance and resistance are associated.
+ /**
+ * How the fault impedance and resistance are connected to the ground.
+ */
  enum ConnectionType {
  SERIES,
  PARALLEL,
  }
 
- // What kind of fault is simulated
+ /**
+ * The type of fault being simulated.
+ */
  enum FaultType {
  THREE_PHASE,
  SINGLE_PHASE,
  }
 
  //TODO : add the numbers of the phase for two and single phase
 
- // The fault id.
+ /**
+ * The ID of the fault.
+ */
  String getId();
 
- // The equipment or bus id where the fault is simulated.
+ /**
+ * The ID of the equipment or bus associated to this fault.
+ */
  String getElementId();
 
- // Characteristics of the short circuit to ground.
+ /**
+ * The resistance of the fault to the ground. The default is zero Ohms.
+ */
  double getRToGround();
 
+ /**
+ * The reactance of the fault to the ground. The default is zero Ohms.
+ */
  double getXToGround();
 
+ /**
+ * The type of the element associated to the fault: can be BUS or BRANCH.
+ */
  Type getType();
 
+ /**
+ * How the fault resistance and reactance are connected to the ground. Can be SERIES or PARALLEL.
+ */
  ConnectionType getConnectionType();
 
+ /**
+ * The type of fault occurring on the network element: can be THREE-PHASE or SINGLE-PHASE.
+ */
  FaultType getFaultType();
 
  private static ObjectMapper createObjectMapper() {
  return JsonUtil.createObjectMapper().registerModule(new ShortCircuitAnalysisJsonModule());
  }
 
+ /**
+ * Writes a list of faults to a JSON file
+ * @param faults the list of faults
+ * @param jsonFile the path to the JSON file
+ */
  static void write(List<Fault> faults, Path jsonFile) {
  try (OutputStream out = Files.newOutputStream(jsonFile)) {
  createObjectMapper().writerWithDefaultPrettyPrinter().writeValue(out, faults);
@@ -76,6 +104,11 @@ static void write(List<Fault> faults, Path jsonFile) {
  }
  }
 
+ /**
+ * Reads a JSON file and creates the associated list of faults
+ * @param jsonFile the path to the existing JSON file
+ * @return a list of faults
+ */
  static List<Fault> read(Path jsonFile) {
  try (InputStream is = Files.newInputStream(jsonFile)) {
  return createObjectMapper().readerForListOf(Fault.class).readValue(is);

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultParameters.java

@@ -27,6 +27,8 @@
 import static com.powsybl.shortcircuit.VoltageRange.checkVoltageRange;
 
 /**
+ * Class to override general short-circuit analysis parameters and make them specific to a particular fault.
+ *
  * @author Thomas Adam {@literal <tadam at silicom.fr>}
  */
 public class FaultParameters {
@@ -241,6 +243,11 @@ private static ObjectMapper createObjectMapper() {
  return JsonUtil.createObjectMapper().registerModule(new ShortCircuitAnalysisJsonModule());
  }
 
+ /**
+ * Writes a list of FaultParameters to a JSON file
+ * @param parameters the list of FaultParameters
+ * @param jsonFile the path to the JSON file
+ */
  public static void write(List<FaultParameters> parameters, Path jsonFile) {
  try (OutputStream out = Files.newOutputStream(jsonFile)) {
  createObjectMapper().writerWithDefaultPrettyPrinter().writeValue(out, parameters);
@@ -249,6 +256,11 @@ public static void write(List<FaultParameters> parameters, Path jsonFile) {
  }
  }
 
+ /**
+ * Reads a JSON file and creates the associated list of FaultParameters
+ * @param jsonFile the path to the JSON file
+ * @return a list of FaultParameters
+ */
  public static List<FaultParameters> read(Path jsonFile) {
  try (InputStream is = Files.newInputStream(jsonFile)) {
  return createObjectMapper().readerForListOf(FaultParameters.class).readValue(is);
@@ -257,6 +269,9 @@ public static List<FaultParameters> read(Path jsonFile) {
  }
  }
 
+ /**
+ * Method used to validate FaultParameters. The voltage ranges should be defined if the parameter initialVoltageProfileMode is set to CONFIGURED.
+ */
  public void validate() {
  if (initialVoltageProfileMode == InitialVoltageProfileMode.CONFIGURED && (voltageRanges == null || voltageRanges.isEmpty())) {
  throw new PowsyblException("Configured initial voltage profile but nominal voltage ranges with associated coefficients are missing.");

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FaultResult.java

@@ -14,13 +14,18 @@
 import java.util.List;
 
 /**
+ * Interface to describe the result of the short-circuit analysis for a given fault.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public interface FaultResult extends Extendable<FaultResult> {
 
+ /**
+ * The status of the computation.
+ */
  enum Status {
  /**
- * The computation went ok and no error were returned
+ * The computation went ok and no error was returned
  */
  SUCCESS,
  /**

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FeederResult.java

@@ -13,6 +13,8 @@
 import javax.annotation.Nullable;
 
 /**
+ * Interface to describe the contribution of a feeder to the short-circuit current after the analysis.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public interface FeederResult {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFaultResult.java

@@ -14,7 +14,7 @@
 import java.util.List;
 
 /**
- * Results for one fault computation with currents and voltage on the three phases.
+ * Results of the short-circuit calculation with the voltage and currents detailed on the three phases.
  *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueFeederResult.java

@@ -10,6 +10,8 @@
 import com.powsybl.iidm.network.ThreeSides;
 
 /**
+ * Result detailed on the three phases for a feeder contributing to the short-circuit current.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public class FortescueFeederResult extends AbstractFeederResult {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueShortCircuitBusResults.java

@@ -8,6 +8,8 @@
 package com.powsybl.shortcircuit;
 
 /**
+ * Results detailed on the three phases of the voltages on a bus.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public class FortescueShortCircuitBusResults extends AbstractShortCircuitBusResults {

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/FortescueValue.java

@@ -39,26 +39,44 @@ public ThreePhaseValue(double magnitudeA, double magnitudeB, double magnitudeC,
  this.angleC = angleC;
  }
 
+ /**
+ * The magnitude on phase A
+ */
  public double getMagnitudeA() {
  return magnitudeA;
  }
 
+ /**
+ * The magnitude on phase B
+ */
  public double getMagnitudeB() {
  return magnitudeB;
  }
 
+ /**
+ * The magnitude on phase C
+ */
  public double getMagnitudeC() {
  return magnitudeC;
  }
 
+ /**
+ * The angle on phase A
+ */
  public double getAngleA() {
  return angleA;
  }
 
+ /**
+ * The angle on phase B
+ */
  public double getAngleB() {
  return angleB;
  }
 
+ /**
+ * The angle on phase C
+ */
  public double getAngleC() {
  return angleC;
  }
@@ -89,30 +107,52 @@ public FortescueValue(double positiveMagnitude) {
  this(positiveMagnitude, Double.NaN, Double.NaN, Double.NaN, Double.NaN, Double.NaN);
  }
 
+ /**
+ * The magnitude on the positive sequence
+ */
  public double getPositiveMagnitude() {
  return positiveMagnitude;
  }
 
+ /**
+ * The magnitude on the zero sequence
+ */
  public double getZeroMagnitude() {
  return zeroMagnitude;
  }
 
+ /**
+ * The magnitude on the negative sequence
+ */
  public double getNegativeMagnitude() {
  return negativeMagnitude;
  }
 
+ /**
+ * The angle on the positive sequence
+ */
  public double getPositiveAngle() {
  return positiveAngle;
  }
 
+ /**
+ * The angle on the zero sequence
+ */
  public double getZeroAngle() {
  return zeroAngle;
  }
 
+ /**
+ * The angle on the negative sequence
+ */
  public double getNegativeAngle() {
  return negativeAngle;
  }
 
+ /**
+ * Convert the value from the positive, zero and negative sequence to the A, B and C phase components.
+ * @return the three phase components.
+ */
  public ThreePhaseValue toThreePhaseValue() {
 
  // [G1] [ 1 1 1 ] [Gh]

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/InitialVoltageProfileMode.java

@@ -8,11 +8,24 @@
 package com.powsybl.shortcircuit;
 
 /**
+ * The initial voltage profile to consider for the computation.
+ *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */
 public enum InitialVoltageProfileMode {
+ /**
+ * The nominal values of the voltage are used.
+ */
  NOMINAL,
- CONFIGURED, // Voltage profile given by the user
- PREVIOUS_VALUE // Voltage profile from the loadflow
+
+ /**
+ * The user gives the voltage profile.
+ */
+ CONFIGURED,
+
+ /**
+ * The voltage profile used is the one calculated by the load flow calculation.
+ */
+ PREVIOUS_VALUE
 
 }

shortcircuit-api/src/main/java/com/powsybl/shortcircuit/MagnitudeFaultResult.java

@@ -14,7 +14,7 @@
 import java.util.List;
 
 /**
- * Results for one fault computation with current magnitude.
+ * Results for one fault with three-phase current magnitude.
  *
  * @author Coline Piloquet {@literal <coline.piloquet at rte-france.com>}
  */