Merge pull request #424 from dariuszzbyrad/boardinfo-add-missing-java…

…docs

Add Javadoc comments and small refactor code

pi4j-core/src/main/java/com/pi4j/boardinfo/definition/BoardModel.java

@@ -1,5 +1,30 @@
 package com.pi4j.boardinfo.definition;
 
+/*-
+ * #%L
+ * **********************************************************************
+ * ORGANIZATION  :  Pi4J
+ * PROJECT       :  Pi4J :: LIBRARY  :: Java Library (CORE)
+ * FILENAME      :  BoardModel.java
+ *
+ * This file is part of the Pi4J project. More information about
+ * this project can be found here:  https://pi4j.com/
+ * **********************************************************************
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -12,15 +37,15 @@
 import static com.pi4j.boardinfo.definition.BoardType.*;
 
 /**
- * Partially based on:
+ * Represents various Raspberry Pi board models along with their specifications and attributes.
  *
- * <ul>
- *      <li>Board codes: <a href="https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#new-style-revision-codes-in-use">raspberrypi.com/documentation/computers/raspberry-pi.html#new-style-revision-codes-in-use</a></li>
- *      <li>Old-style: <a href="https://github.com/raspberrypi/documentation/blob/develop/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc">github.com/raspberrypi/documentation/blob/develop/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc</a></li>
- *      </li><li><a href="https://en.wikipedia.org/wiki/Raspberry_Pi#Specifications">en.wikipedia.org/wiki/Raspberry_Pi</a></li>
- *      <li><a href="https://oastic.com/posts/how-to-know-which-raspberry-do-you-have/">oastic.com/posts/how-to-know-which-raspberry-do-you-have</a></li>
- *      <li><a href="https://www.raspberrypi-spy.co.uk/2012/09/checking-your-raspberry-pi-board-version/">raspberrypi-spy.co.uk/2012/09/checking-your-raspberry-pi-board-version/</a></li>
- * </ul>
+ * <p>This class is partially based on resources such as Raspberry Pi documentation, GitHub, and other online references.</p>
+ *
+ * @see <a href="https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#new-style-revision-codes-in-use">Board Codes</a>
+ * @see <a href="https://github.com/raspberrypi/documentation/blob/develop/documentation/asciidoc/computers/raspberry-pi/revision-codes.adoc">Old-style Revision Codes</a>
+ * @see <a href="https://en.wikipedia.org/wiki/Raspberry_Pi#Specifications">Raspberry Pi Specifications</a>
+ * @see <a href="https://oastic.com/posts/how-to-know-which-raspberry-do-you-have/">How to Identify Your Raspberry Pi</a>
+ * @see <a href="https://www.raspberrypi-spy.co.uk/2012/09/checking-your-raspberry-pi-board-version/">Checking Your Raspberry Pi Board Version</a>
  */
 public enum BoardModel {
     MODEL_1_A("Raspberry Pi 1 Model A", SINGLE_BOARD_COMPUTER,
@@ -277,14 +302,45 @@ public enum BoardModel {
     private final List<Integer> versionsMemoryInKb;
     private final List<String> remarks;
 
+    /**
+     * Constructor for creating a {@code BoardModel} without remarks.
+     *
+     * @param label the descriptive name of the board
+     * @param boardType the type of the board
+     * @param boardCodes a list of unique codes identifying this board
+     * @param model the Pi model of the board
+     * @param headerVersion the header version
+     * @param releaseDate the release date of the board
+     * @param soc the system-on-chip used
+     * @param cpu the CPU type
+     * @param numberOfCpu the number of CPU cores
+     * @param versionsProcessorSpeedInMhz list of processor speeds in MHz
+     * @param versionsMemoryInKb list of memory sizes in KB
+     */
     BoardModel(String label, BoardType boardType, List<String> boardCodes,
                PiModel model, HeaderVersion headerVersion, LocalDate releaseDate,
                Soc soc, Cpu cpu, Integer numberOfCpu,
                List<Integer> versionsProcessorSpeedInMhz, List<Integer> versionsMemoryInKb) {
-        this(label, boardType, boardCodes, model, headerVersion, releaseDate, soc, cpu, numberOfCpu, versionsProcessorSpeedInMhz,
-            versionsMemoryInKb, new ArrayList<>());
+        this(label, boardType, boardCodes, model, headerVersion, releaseDate, soc, cpu, numberOfCpu,
+            versionsProcessorSpeedInMhz, versionsMemoryInKb, new ArrayList<>());
     }
 
+    /**
+     * Constructor for creating a {@code BoardModel}.
+     *
+     * @param label the descriptive name of the board
+     * @param boardType the type of the board
+     * @param boardCodes a list of unique codes identifying this board
+     * @param model the Pi model of the board
+     * @param headerVersion the header version
+     * @param releaseDate the release date of the board
+     * @param soc the system-on-chip used
+     * @param cpu the CPU type
+     * @param numberOfCpu the number of CPU cores
+     * @param versionsProcessorSpeedInMhz list of processor speeds in MHz
+     * @param versionsMemoryInKb list of memory sizes in KB
+     * @param remarks any remarks or notes about the board
+     */
     BoardModel(String label, BoardType boardType, List<String> boardCodes,
                PiModel model, HeaderVersion headerVersion, LocalDate releaseDate,
                Soc soc, Cpu cpu, Integer numberOfCpu,
@@ -304,18 +360,31 @@ public enum BoardModel {
         this.remarks = remarks;
     }
 
+    /**
+     * Retrieves the board model corresponding to the given board code.
+     *
+     * @param boardCode the board code to look up
+     * @return the matching {@code BoardModel} or {@code UNKNOWN} if no match is found
+     * @throws Exception if multiple matches are found
+     */
     public static BoardModel getByBoardCode(String boardCode) throws Exception {
         var matches = Arrays.stream(BoardModel.values())
             .filter(bm -> bm.boardCodes.contains(boardCode))
             .collect(Collectors.toList());
         if (matches.isEmpty()) {
             return BoardModel.UNKNOWN;
         } else if (matches.size() > 1) {
-            throw (new Exception("Too many matching models found for code " + boardCode + ", probably an error in the definitions"));
+            throw new Exception("Too many matching models found for code " + boardCode);
         }
         return matches.get(0);
     }
 
+    /**
+     * Retrieves the board model corresponding to the given board name.
+     *
+     * @param boardName the name of the board
+     * @return the matching {@code BoardModel} or {@code UNKNOWN} if no match is found
+     */
     public static BoardModel getByBoardName(String boardName) {
         var matches = Arrays.stream(BoardModel.values())
             .filter(bm -> boardName.toLowerCase().startsWith(bm.label.toLowerCase()))
@@ -328,69 +397,118 @@ public static BoardModel getByBoardName(String boardName) {
         return matches.get(0);
     }
 
+    /**
+     * Retrieves all unique board codes from all models.
+     *
+     * @return a list of all board codes
+     */
     public static List<String> getAllBoardCodes() {
         return Arrays.stream(BoardModel.values())
-            .map(b -> b.boardCodes)
-            .flatMap(List::stream)  // Flatten the nested lists into a single stream
-            .collect(Collectors.toList()); // Collect elements into one list
+            .flatMap(b -> b.boardCodes.stream())
+            .collect(Collectors.toList());
     }
 
+    /**
+     * @return the enum name of the board model
+     */
     public String getName() {
         return name();
     }
 
+    /**
+     * @return the label of the board model
+     */
     public String getLabel() {
         return label;
     }
 
+    /**
+     * @return the board type
+     */
     public BoardType getBoardType() {
         return boardType;
     }
 
+    /**
+     * @return the list of board codes
+     */
     public List<String> getBoardCodes() {
         return boardCodes;
     }
 
+    /**
+     * @return the Pi model of the board
+     */
     public PiModel getModel() {
         return model;
     }
 
+    /**
+     * @return the header version of the board
+     */
     public HeaderVersion getHeaderVersion() {
         return headerVersion;
     }
 
+    /**
+     * @return the release date of the board
+     */
     public LocalDate getReleaseDate() {
         return releaseDate;
     }
 
+    /**
+     * @return the system-on-chip used by the board
+     */
     public Soc getSoc() {
         return soc;
     }
 
+    /**
+     * @return the CPU type used by the board
+     */
     public Cpu getCpu() {
         return cpu;
     }
 
+    /**
+     * @return the number of CPU cores
+     */
     public Integer getNumberOfCpu() {
         return numberOfCpu;
     }
 
+    /**
+     * @return a list of processor speeds in MHz
+     */
     public List<Integer> getVersionsProcessorSpeedInMhz() {
         return versionsProcessorSpeedInMhz;
     }
 
+    /**
+     * @return a list of memory sizes in KB
+     */
     public List<Integer> getVersionsMemoryInKb() {
         return versionsMemoryInKb;
     }
 
+    /**
+     * @return a list of memory sizes in MB
+     */
     public List<Float> getVersionsMemoryInMb() {
         return versionsMemoryInKb.stream().map(m -> m / 1024F).collect(Collectors.toList());
     }
 
+    /**
+     * @return a list of memory sizes in GB
+     */
     public List<Float> getVersionsMemoryInGb() {
         return versionsMemoryInKb.stream().map(m -> m / 1024F / 1024F).collect(Collectors.toList());
     }
 
+    /**
+     * @return any remarks associated with the board
+     */
     public List<String> getRemarks() {
         return remarks;
     }

pi4j-core/src/main/java/com/pi4j/boardinfo/definition/BoardType.java

@@ -1,9 +1,57 @@
 package com.pi4j.boardinfo.definition;
 
+/*-
+ * #%L
+ * **********************************************************************
+ * ORGANIZATION  :  Pi4J
+ * PROJECT       :  Pi4J :: LIBRARY  :: Java Library (CORE)
+ * FILENAME      :  BoardType.java
+ *
+ * This file is part of the Pi4J project. More information about
+ * this project can be found here:  https://pi4j.com/
+ * **********************************************************************
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+
+/**
+ * Represents the types of boards available in the Pi4J Board Information API.
+ */
 public enum BoardType {
+
+    /**
+     * Represents an all-in-one computer board type, such as the Raspberry Pi 400.
+     */
     ALL_IN_ONE_COMPUTER,
+
+    /**
+     * Represents a microcontroller board type, such as the Raspberry Pi Pico.
+     */
     MICROCONTROLLER,
+
+    /**
+     * Represents a single-board computer (SBC) type, such as the Raspberry Pi Model B series.
+     */
     SINGLE_BOARD_COMPUTER,
+
+    /**
+     * Represents a stack-on computer module type, such as the Compute Module series.
+     */
     STACK_ON_COMPUTER,
+
+    /**
+     * Represents an unknown board type.
+     */
     UNKNOWN
 }