fix: missing Javadoc

Author: ppkarwasz

src/main/java/org/apache/commons/build/BuildAttestationMojo.java

@@ -124,6 +124,15 @@ public class BuildAttestationMojo extends AbstractMojo {
      */
     private final MavenProjectHelper mavenProjectHelper;
 
+    /**
+     * Creates a new instance with the given dependencies.
+     *
+     * @param project A Maven project.
+     * @param scmManager A SCM manager.
+     * @param runtimeInformation Maven runtime information.
+     * @param session A Maven session.
+     * @param mavenProjectHelper A helper to attach artifacts to the project.
+     */
     @Inject
     public BuildAttestationMojo(MavenProject project, ScmManager scmManager, RuntimeInformation runtimeInformation, MavenSession session,
             MavenProjectHelper mavenProjectHelper) {
@@ -138,10 +147,20 @@ void setOutputDirectory(File outputDirectory) {
         this.outputDirectory = outputDirectory;
     }
 
+    /**
+     * Returns the SCM directory.
+     *
+     * @return The SCM directory.
+     */
     public File getScmDirectory() {
         return scmDirectory;
     }
 
+    /**
+     * Sets the SCM directory.
+     *
+     * @param scmDirectory The SCM directory.
+     */
     public void setScmDirectory(File scmDirectory) {
         this.scmDirectory = scmDirectory;
     }

src/main/java/org/apache/commons/build/internal/ArtifactUtils.java

@@ -25,16 +25,32 @@
 import org.apache.maven.artifact.Artifact;
 import org.apache.maven.plugin.MojoExecutionException;
 
+/**
+ * Utilities to convert {@link Artifact} from and to other types.
+ */
 public final class ArtifactUtils {
 
     private ArtifactUtils() {
         // prevent instantiation
     }
 
+    /**
+     * Returns the conventional filename for the given artifact.
+     *
+     * @param artifact A Maven artifact.
+     * @return A filename.
+     */
     public static String getFileName(Artifact artifact) {
         return getFileName(artifact, artifact.getArtifactHandler().getExtension());
     }
 
+    /**
+     * Returns the filename for the given artifact with a changed extension.
+     *
+     * @param artifact A Maven artifact.
+     * @param extension The file name extension.
+     * @return A filename.
+     */
     public static String getFileName(Artifact artifact, String extension) {
         StringBuilder fileName = new StringBuilder();
         fileName.append(artifact.getArtifactId()).append("-").append(artifact.getVersion());
@@ -45,6 +61,12 @@ public static String getFileName(Artifact artifact, String extension) {
         return fileName.toString();
     }
 
+    /**
+     * Returns the Package URL corresponding to this artifact.
+     *
+     * @param artifact A maven artifact.
+     * @return A PURL for the given artifact.
+     */
     public static String getPackageUrl(Artifact artifact) {
         StringBuilder sb = new StringBuilder();
         sb.append("pkg:maven/").append(artifact.getGroupId()).append("/").append(artifact.getArtifactId()).append("@").append(artifact.getVersion())
@@ -57,14 +79,21 @@ public static String getPackageUrl(Artifact artifact) {
         return sb.toString();
     }
 
-    public static Map<String, String> getChecksums(Artifact artifact) throws IOException {
+    private static Map<String, String> getChecksums(Artifact artifact) throws IOException {
         Map<String, String> checksums = new HashMap<>();
         DigestUtils digest = new DigestUtils(DigestUtils.getSha256Digest());
         String sha256sum = digest.digestAsHex(artifact.getFile());
         checksums.put("sha256", sha256sum);
         return checksums;
     }
 
+    /**
+     * Converts a Maven artifact to a SLSA {@link ResourceDescriptor}.
+     *
+     * @param artifact A Maven artifact.
+     * @return A SLSA resource descriptor.
+     * @throws MojoExecutionException If an I/O error occurs retrieving the artifact.
+     */
     public static ResourceDescriptor toResourceDescriptor(Artifact artifact) throws MojoExecutionException {
         ResourceDescriptor descriptor = new ResourceDescriptor();
         descriptor.setName(getFileName(artifact));

src/main/java/org/apache/commons/build/internal/GitUtils.java

@@ -26,8 +26,18 @@
 import java.nio.file.Paths;
 import java.security.MessageDigest;
 
+/**
+ * Utilities for Git operations.
+ */
 public final class GitUtils {
 
+    /**
+     * Returns the Git tree hash for the given directory.
+     *
+     * @param path A directory path.
+     * @return A hex-encoded SHA-1 tree hash.
+     * @throws IOException If the path is not a directory or an I/O error occurs.
+     */
     public static String gitTree(Path path) throws IOException {
         if (!Files.isDirectory(path)) {
             throw new IOException("Path is not a directory: " + path);
@@ -36,6 +46,13 @@ public static String gitTree(Path path) throws IOException {
         return Hex.encodeHexString(DigestUtils.gitTree(digest, path));
     }
 
+    /**
+     * Returns the Git blob hash for the given file.
+     *
+     * @param path A regular file path.
+     * @return A hex-encoded SHA-1 blob hash.
+     * @throws IOException If the path is not a regular file or an I/O error occurs.
+     */
     public static String gitBlob(Path path) throws IOException {
         if (!Files.isRegularFile(path)) {
             throw new IOException("Path is not a regular file: " + path);
@@ -44,6 +61,14 @@ public static String gitBlob(Path path) throws IOException {
         return Hex.encodeHexString(DigestUtils.gitBlob(digest, path));
     }
 
+    /**
+     * Converts an SCM URI to a download URI suffixed with the current branch name.
+     *
+     * @param scmUri A Maven SCM URI starting with {@code scm:git}.
+     * @param repositoryPath A path inside the Git repository.
+     * @return A download URI of the form {@code git+<url>@<branch>}.
+     * @throws IOException If the current branch cannot be determined.
+     */
     public static String scmToDownloadUri(String scmUri, Path repositoryPath) throws IOException {
         if (!scmUri.startsWith("scm:git")) {
             throw new IllegalArgumentException("Invalid scmUri: " + scmUri);
@@ -52,6 +77,15 @@ public static String scmToDownloadUri(String scmUri, Path repositoryPath) throws
         return "git+" + scmUri.substring(8) + "@" + currentBranch;
     }
 
+    /**
+     * Returns the current branch name for the given repository path.
+     *
+     * <p>Returns the commit SHA if the repository is in a detached HEAD state.
+     *
+     * @param repositoryPath A path inside the Git repository.
+     * @return The current branch name, or the commit SHA for a detached HEAD.
+     * @throws IOException If the {@code .git} directory cannot be found or read.
+     */
     public static String getCurrentBranch(Path repositoryPath) throws IOException {
         Path gitDir = findGitDir(repositoryPath);
         String head = new String(Files.readAllBytes(gitDir.resolve("HEAD")), StandardCharsets.UTF_8).trim();

src/main/java/org/apache/commons/build/models/slsa/v1_2/package-info.java

@@ -18,99 +18,13 @@
 /**
  * SLSA 1.2 Build Attestation Models.
  *
- * <p>This package provides Jackson-annotated model classes that implement the <a
- * href="https://slsa.dev/spec/v1.2">Supply-chain Levels for Software Artifacts (SLSA) v1.2
- * specification</a>.
+ * <p>This package provides Jackson-annotated model classes that implement the <a href="https://slsa.dev/spec/v1.2">Supply-chain Levels for Software Artifacts
+ * (SLSA) v1.2 specification</a>.</p>
  *
  * <h2>Overview</h2>
  *
- * <p>SLSA is a framework for evaluating and improving the security posture of build systems. SLSA
- * v1.2 defines a standard for recording build provenance - information about how software
- * artifacts were produced.
- *
- * <h2>Core Models</h2>
- *
- * <ul>
- *   <li><b>{@link org.apache.commons.build.models.slsa.v1_2.Provenance}</b> - Root object
- *       describing the build provenance. Contains BuildDefinition and RunDetails.
- *   <li><b>{@link org.apache.commons.build.models.slsa.v1_2.BuildDefinition}</b> - Specifies
- *       the inputs that define the build, including build type, configuration, external
- *       parameters, and resolved dependencies.
- *   <li><b>{@link org.apache.commons.build.models.slsa.v1_2.RunDetails}</b> - Specifies the
- *       details about the build invocation and environment, including the builder identity and
- *       build metadata.
- * </ul>
- *
- * <h2>Supporting Models</h2>
- *
- * <ul>
- *   <li><b>{@link org.apache.commons.build.models.slsa.v1_2.Builder}</b> - Identifies the
- *       entity that executed the build.
- *   <li><b>{@link org.apache.commons.build.models.slsa.v1_2.BuildMetadata}</b> - Contains
- *       metadata about the build invocation, including timing information.
- *   <li><b>{@link org.apache.commons.build.models.slsa.v1_2.ResourceDescriptor}</b> - Describes
- *       an artifact or resource referenced in the build by URI and cryptographic digest.
- * </ul>
- *
- * <h2>Usage Example</h2>
- *
- * <pre>
- * // Create a builder
- * Builder builder = new Builder();
- * builder.setId("https://github.com/actions");
- * builder.setVersion("1.0");
- *
- * // Create build metadata
- * BuildMetadata buildMetadata = new BuildMetadata();
- * buildMetadata.setInvocationId("build-12345");
- * buildMetadata.setStartedOn(OffsetDateTime.now(ZoneOffset.UTC));
- * buildMetadata.setFinishedOn(OffsetDateTime.now(ZoneOffset.UTC));
- *
- * // Create run details
- * RunDetails runDetails = new RunDetails();
- * runDetails.setBuilder(builder);
- * runDetails.setMetadata(buildMetadata);
- *
- * // Create build definition
- * BuildDefinition buildDefinition = new BuildDefinition();
- * buildDefinition.setBuildType("https://github.com/actions");
- * buildDefinition.setExternalParameters(new HashMap<>());
- *
- * // Create provenance
- * Provenance provenance = new Provenance();
- * provenance.setBuildDefinition(buildDefinition);
- * provenance.setRunDetails(runDetails);
- *
- * // Serialize with Jackson
- * ObjectMapper mapper = new ObjectMapper();
- * String json = mapper.writeValueAsString(provenance);
- * </pre>
- *
- * <h2>Jackson Integration</h2>
- *
- * <p>All models use Jackson annotations for JSON serialization/deserialization:
- *
- * <ul>
- *   <li>{@code @JsonProperty} - Maps field names to JSON properties
- *   <li>{@code @JsonInclude} - Controls inclusion of null/empty values in serialization
- *   <li>{@code @JsonFormat} - Specifies date/time formatting
- * </ul>
- *
- * <p>The models are compatible with Jackson's ObjectMapper and support both serialization to
- * JSON and deserialization from JSON.
- *
- * <h2>Validation</h2>
- *
- * <p>Some models include Jakarta Validation annotations:
- *
- * <ul>
- *   <li>{@code @NotBlank} - Ensures required string fields are not empty
- * </ul>
- *
- * <p>Users can enable validation using a Jakarta Validation provider to ensure provenance
- * integrity.
- *
- * <h2>Reference</h2>
+ * <p>SLSA is a framework for evaluating and improving the security posture of build systems. SLSA v1.2 defines a standard for recording build provenance:
+ * information about how software artifacts were produced.</p>
  *
  * @see <a href="https://slsa.dev/spec/v1.2">SLSA v1.2 Specification</a>
  * @see <a href="https://github.com/in-toto/attestation">In-toto Attestation Framework</a>