Misc doc and API cleanups

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/ResourceUtilities.java

@@ -1,13 +1,9 @@
 package com.microsoft.aspire.implementation;
 
 import com.microsoft.aspire.resources.Resource;
-import com.microsoft.aspire.resources.annotations.EndpointAnnotation;
-import com.microsoft.aspire.resources.annotations.EndpointReferenceAnnotation;
-import com.microsoft.aspire.resources.annotations.EnvironmentAnnotation;
-import com.microsoft.aspire.resources.annotations.EnvironmentCallbackAnnotation;
+import com.microsoft.aspire.resources.annotations.*;
 import com.microsoft.aspire.resources.properties.*;
 import com.microsoft.aspire.resources.references.EndpointReference;
-import com.microsoft.aspire.resources.annotations.ResourceAnnotation;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
 import com.microsoft.aspire.resources.traits.ResourceWithEnvironment;
 

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/implementation/utils/json/ResourceSerializer.java

@@ -9,10 +9,7 @@
 import com.microsoft.aspire.implementation.ResourceUtilities;
 import com.microsoft.aspire.resources.DockerFile;
 import com.microsoft.aspire.resources.Resource;
-import com.microsoft.aspire.resources.annotations.ArgsAnnotation;
-import com.microsoft.aspire.resources.annotations.EndpointAnnotation;
-import com.microsoft.aspire.resources.annotations.EnvironmentCallbackAnnotation;
-import com.microsoft.aspire.resources.annotations.KeyValueAnnotation;
+import com.microsoft.aspire.resources.annotations.*;
 import com.microsoft.aspire.resources.properties.*;
 import com.microsoft.aspire.resources.references.ReferenceExpression;
 import com.microsoft.aspire.resources.traits.ManifestExpressionProvider;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/DockerFile.java

@@ -103,6 +103,7 @@ public T withPath(String path) {
     /**
      * Sets the path to the context that will be used to build a container image. The path must be relative to the root
      * directory, i.e. from where azd is being executed from.
+     *
      * @param context A path to the context, relative to the directory where azd will be executed from.
      * @return The DockerFile object.
      */

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/Executable.java

@@ -1,52 +1,21 @@
 package com.microsoft.aspire.resources;
 
-import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
 import com.microsoft.aspire.resources.traits.ResourceWithArguments;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;
 import com.microsoft.aspire.resources.traits.ResourceWithEnvironment;
 import com.microsoft.aspire.resources.traits.ResourceWithReference;
-import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 
-import java.util.*;
-
-/*
-{
-    "type": "object",
-    "description": "Represents an executable resource.",
-    "required": [
-        "type",
-        "command",
-        "workingDirectory"
-    ],
-    "properties": {
-        "type": {
-            "const": "executable.v0"
-        },
-        "workingDirectory": {
-            "type": "string",
-            "description": "The path to the working directory. Should be intepretted as being relative to the AppHost directory."
-        },
-        "command": {
-            "type": "string",
-            "description": "The path to the command. Should be interpreted as being relative to the AppHost directory."
-        },
-        "args": {
-            "$ref": "#/definitions/args"
-        },
-        "env": {
-            "$ref": "#/definitions/env"
-        },
-        "bindings": {
-            "$ref": "#/definitions/bindings"
-        }
-    },
-    "additionalProperties": false
-},
+/**
+ * Represents an executable resource.
+ *
+ * @param <T> The specific type of the resource, which may or may not be a subtype of this class. This allows for
+ *            method chaining, even when using a subtype, when used in conjunction with the API on
+ *            {@link com.microsoft.aspire.resources.traits.SelfAware}.
  */
 @JsonPropertyOrder({"type", "workingDirectory", "command", "args", "env", "bindings"})
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
@@ -77,11 +46,23 @@ public Executable(String name, String workingDirectory, String command) {
         this.command = command;
     }
 
+    /**
+     * The path to the working directory. Should be interpreted as being relative to the AppHost directory.
+     *
+     * @param workingDirectory The path to the working directory.
+     * @return The Executable resource.
+     */
     public T withWorkingDirectory(String workingDirectory) {
         this.workingDirectory = workingDirectory;
         return self();
     }
 
+    /**
+     * The path to the command. Should be interpreted as being relative to the AppHost directory.
+     *
+     * @param command The path to the command.
+     * @return The Executable resource.
+     */
     public T withCommand(String command) {
         this.command = command;
         return self();

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/ResourceType.java

@@ -4,12 +4,34 @@
 import jakarta.validation.constraints.NotEmpty;
 import jakarta.validation.constraints.NotNull;
 
+/**
+ * An expandable enum-like type for specifying the type of a resource. This is used to determine how to process the
+ * resource when being processed by tools such as azd.
+ */
 public class ResourceType {
+    /**
+     * An Azure Bicep file - consider using {@link AzureBicepResource}.
+     */
     public static final ResourceType AZURE_BICEP = fromString("azure.bicep.v0");
+
+    /**
+     * A container resource - consider using {@link Container}.
+     */
     public static final ResourceType CONTAINER = fromString("container.v0");
+
+    /**
+     * A Dockerfile resource - consider using {@link DockerFile}.
+     */
     public static final ResourceType DOCKER_FILE = fromString("dockerfile.v0");
+
+    /**
+     * An executable resource - consider using {@link Executable}.
+     */
     public static final ResourceType EXECUTABLE = fromString("executable.v0");
-    public static final ResourceType PROJECT = fromString("project.v0");
+
+    /**
+     * A value resource - consider using {@link Value}.
+     */
     public static final ResourceType VALUE = fromString("value.v0");
 
     @NotNull(message = "Resource type cannot be null")
@@ -20,6 +42,11 @@ private ResourceType(String value) {
         this.value = value;
     }
 
+    /**
+     * Creates a new ResourceType with the given value as the type.
+     * @param value The value of the new ResourceType.
+     * @return A new ResourceType with the given value as the type.
+     */
     public static ResourceType fromString(String value) {
         if (value == null) {
             throw new IllegalArgumentException("Resource type cannot be null");

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/annotations/EnvironmentCallbackAnnotation.java

@@ -1,7 +1,5 @@
 package com.microsoft.aspire.resources.annotations;
 
-import com.microsoft.aspire.resources.properties.EnvironmentCallbackContext;
-
 import java.util.function.Consumer;
 import java.util.function.Supplier;
 

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/properties/EnvironmentCallbackContext.java → aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/annotations/EnvironmentCallbackContext.java

@@ -1,4 +1,4 @@
-package com.microsoft.aspire.resources.properties;
+package com.microsoft.aspire.resources.annotations;
 
 import java.util.Collections;
 import java.util.Map;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/properties/Protocol.java

@@ -2,8 +2,18 @@
 
 import com.fasterxml.jackson.annotation.JsonValue;
 
+/**
+ * Network protocol: TCP or UDP are supported today, others possibly in future.
+ */
 public enum Protocol {
+    /**
+     * Transmission Control Protocol.
+     */
     TCP("tcp"),
+
+    /**
+     * User Datagram Protocol.
+     */
     UDP("udp");
 
     private final String value;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/properties/Scheme.java

@@ -2,10 +2,28 @@
 
 import com.fasterxml.jackson.annotation.JsonValue;
 
+/**
+ * The network scheme: HTTP, HTTPS, TCP, or UDP.
+ */
 public enum Scheme {
+    /**
+     * HTTP scheme.
+     */
     HTTP("http"),
+
+    /**
+     * HTTPS scheme.
+     */
     HTTPS("https"),
+
+    /**
+     * TCP scheme.
+     */
     TCP("tcp"),
+
+    /**
+     * UDP scheme.
+     */
     UDP("udp");
 
     private final String value;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/properties/Transport.java

@@ -2,9 +2,23 @@
 
 import com.fasterxml.jackson.annotation.JsonValue;
 
+/**
+ * Transport that is being used (e.g. http, http2, http3 etc).
+ */
 public enum Transport {
+    /**
+     * HTTP transport.
+     */
     HTTP("http"),
+
+    /**
+     * HTTP2 transport.
+     */
     HTTP2("http2"),
+
+    /**
+     * TCP transport.
+     */
     TCP("tcp");
 
     private final String value;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/properties/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Properties that can be applied to resources in various way.
+ */
+package com.microsoft.aspire.resources.properties;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/properties/EndpointProperty.java → aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/references/EndpointProperty.java

@@ -1,4 +1,4 @@
-package com.microsoft.aspire.resources.properties;
+package com.microsoft.aspire.resources.references;
 
 /**
  * Represents the properties of an endpoint that can be referenced.

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/references/EndpointReference.java

@@ -1,10 +1,8 @@
 package com.microsoft.aspire.resources.references;
 
 import com.microsoft.aspire.implementation.TemplateStrings;
-import com.microsoft.aspire.resources.Resource;
 import com.microsoft.aspire.resources.annotations.EndpointAnnotation;
 import com.microsoft.aspire.resources.properties.AllocatedEndpoint;
-import com.microsoft.aspire.resources.properties.EndpointProperty;
 import com.microsoft.aspire.resources.properties.Scheme;
 import com.microsoft.aspire.resources.traits.ManifestExpressionProvider;
 import com.microsoft.aspire.resources.traits.ResourceWithEndpoints;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/references/EndpointReferenceExpression.java

@@ -1,6 +1,5 @@
 package com.microsoft.aspire.resources.references;
 
-import com.microsoft.aspire.resources.properties.EndpointProperty;
 import com.microsoft.aspire.resources.traits.ManifestExpressionProvider;
 import com.microsoft.aspire.resources.traits.ValueProvider;
 import com.microsoft.aspire.resources.traits.ValueWithReferences;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/resources/traits/ResourceWithEnvironment.java

@@ -5,7 +5,7 @@
 import com.microsoft.aspire.resources.Resource;
 import com.microsoft.aspire.resources.references.EndpointReference;
 import com.microsoft.aspire.resources.annotations.EnvironmentCallbackAnnotation;
-import com.microsoft.aspire.resources.properties.EnvironmentCallbackContext;
+import com.microsoft.aspire.resources.annotations.EnvironmentCallbackContext;
 
 import java.net.MalformedURLException;
 import java.net.URI;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/utils/json/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Annotations and other JSON utilities for the purpose of customizing the output of the JSON serializer.
+ */
+package com.microsoft.aspire.utils.json;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/utils/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Utility APIs for use by Aspire4J, extension developers, and / or end users of the Aspire4J library.
+ */
+package com.microsoft.aspire.utils;

aspire4j/aspire4j/src/main/java/com/microsoft/aspire/utils/templates/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * Templating engine and various model types and utility classes for interacting with it.
+ */
+package com.microsoft.aspire.utils.templates;

aspire4j/aspire4j/src/main/java/module-info.java

@@ -1,3 +1,6 @@
+/**
+ * The core module of the Aspire framework, with APIs for specifying and running Aspire resources.
+ */
 module com.microsoft.aspire {
     requires transitive com.fasterxml.jackson.databind;
     requires transitive jakarta.validation;

aspire4j/extensions/azure/eventhubs/src/main/java/module-info.java

@@ -1,5 +1,8 @@
 import com.microsoft.aspire.extensions.azure.eventhubs.AzureEventHubsExtension;
 
+/**
+ * An Aspire extension providing support for Azure Event Hubs.
+ */
 module com.microsoft.aspire.extensions.azure.eventhubs {
     requires transitive com.microsoft.aspire;
 

aspire4j/extensions/azure/openai/src/main/java/module-info.java

@@ -1,5 +1,8 @@
 import com.microsoft.aspire.extensions.azure.openai.AzureOpenAIExtension;
 
+/**
+ * An Aspire extension providing support for Azure OpenAI.
+ */
 module com.microsoft.aspire.extensions.azure.openai {
     requires transitive com.microsoft.aspire;
 

aspire4j/extensions/azure/storage/src/main/java/module-info.java

@@ -1,5 +1,8 @@
 import com.microsoft.aspire.extensions.azure.storage.AzureStorageExtension;
 
+/**
+ * An Aspire extension providing support for Azure Storage.
+ */
 module com.microsoft.aspire.extensions.azure.storage {
     requires transitive com.microsoft.aspire;
 

aspire4j/extensions/dotnet/src/main/java/com/microsoft/aspire/extensions/dotnet/resources/Project.java

@@ -56,6 +56,7 @@
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
 public class Project<T extends Project<T>> extends Resource<T>
            implements ResourceWithArguments<T>, ResourceWithEnvironment<T>, ResourceWithEndpoints<T>, ResourceWithReference<T> {
+    public static final ResourceType PROJECT = ResourceType.fromString("project.v0");
 
     @NotNull(message = "Project.path cannot be null")
     @NotEmpty(message = "Project.path cannot be an empty string")
@@ -64,7 +65,7 @@ public class Project<T extends Project<T>> extends Resource<T>
     private String path;
 
     public Project(String name) {
-        this(ResourceType.PROJECT, name);
+        this(PROJECT, name);
     }
 
     protected Project(ResourceType type, String name) {

aspire4j/extensions/dotnet/src/main/java/module-info.java

@@ -1,5 +1,8 @@
 import com.microsoft.aspire.extensions.dotnet.DotnetExtension;
 
+/**
+ * An Aspire extension providing support for .NET Projects.
+ */
 module com.microsoft.aspire.extensions.dotnet {
     requires transitive com.microsoft.aspire;
     requires java.logging;

aspire4j/extensions/micronaut/src/main/java/module-info.java

@@ -1,5 +1,8 @@
 import com.microsoft.aspire.extensions.micronaut.MicronautExtension;
 
+/**
+ * An Aspire extension providing support for <a href="https://micronaut.io">Micronaut</a> projects.
+ */
 module com.microsoft.aspire.extensions.micronaut {
     requires transitive com.microsoft.aspire.extensions.microservice.common;
     requires java.logging;

aspire4j/extensions/microservice-common/src/main/java/module-info.java

@@ -1,3 +1,6 @@
+/**
+ * An Aspire extension providing the common support for microservice libraries (such as Spring, Micronaut, and Quarkus).
+ */
 module com.microsoft.aspire.extensions.microservice.common {
     requires transitive com.microsoft.aspire;
     requires com.github.javaparser.core;

aspire4j/extensions/quarkus/src/main/java/module-info.java

@@ -1,5 +1,8 @@
 import com.microsoft.aspire.extensions.quarkus.QuarkusExtension;
 
+/**
+ * An Aspire extension providing support for <a href="https://quarkus.io">Quarkus</a> projects.
+ */
 module com.microsoft.aspire.extensions.quarkus {
     requires transitive com.microsoft.aspire.extensions.microservice.common;
     requires java.logging;