docs: update README and add endpoint documentation

README.md

@@ -1,33 +1,25 @@
 # power-server
 
-This project is meant to provide a REST endpoint streaming power consumption, inspired
-by [JoularJX](https://github.com/joular/joularjx) but focusing on exposing power information and metadata over REST
-without further processing.
+This project is meant to provide abstractions over power measurement details, which are platform specific, to enable simplified measure of power consumption, inspired by [JoularJX](https://github.com/joular/joularjx) but focusing on exposing power information and metadata. Several tools are provided, included a REST endpoint and a command-line interface.
 
-This project uses [Quarkus](https://quarkus.io), the Supersonic Subatomic Java Framework and comprises 3 modules:
+This project uses [Quarkus](https://quarkus.io), the Supersonic Subatomic Java Framework and comprises several modules:
 
-- `analysis`, which contains utilities helpful to analyze power measures (computations, statistics, histograms, etc…)
-- `if-manifest-export`, which provides a means to export a stopped measure as
+- `analysis` contains utilities helpful to analyze power measures (computations, statistics, histograms, etc…)
+- `backend` provides the core functionality of the power measurement, including the sampling and sensor logic
+-  `cli` provides a command-line interface to measure power consumption of a specified command
+- `if-manifest-export` provides a means to export a stopped measure as
   a [Green Software Foundation](https://greensoftware.foundation/) [Impact Framework](https://if.greensoftware.foundation/)
   manifest
-- `measure`, which provides classes to help record and process measures in client applications
-- `metadata`, which contains the metadata API that the RESTful server uses to provide information about what is returned
+- `measure` provides classes to help record and process measures in client applications
+- `metadata` defines the metadata API that the RESTful server uses to provide information about what is returned
   by the power sensors. This artifact contains classes that can be reused in client projects.
+- `persistence` provides support to persist measure data to databases (currently, only to SQLite)
 - `server` contains the RESTful server, listening by default on port `20432` (as specified
   in
   `[application.properties](https://github.com/metacosm/power-server/blob/87bba3196fa0e552665b4f1d22006377779b0959/server/src/main/resources/application.properties#L1)`)
 
-The server provides the following endpoints:
 
-- `/power/{pid}` where `pid` is a String representation of a process identifier, identifying a process running on the
-  machine where `power-server` is running.
-- `/power/metadata` provides information about how measures streamed from the main endpoint is formatted as well as
-  information about power components.
-- `/power/sampling` provides the currently configured power measure sampling period, which can be configured using the
-  `net.laprun.sustainability.power.sampling-period` property, passing it a `String` that can be converted to a Java
-  `Duration`.
-
-The main endpoint streams `SensorMeasure` objects as defined in the `metadata`module as an array of double measures.
+The main endpoint streams `SensorMeasure` objects as defined in the `metadata` module as an array of double measures.
 Typically, main sensor components are measured in milli Watts for easier consumption but clients should check the
 information provided by the metadata endpoint to learn the layout of the measures array and which meaning they carry.
 For example, the macOS implementation provides a decimal percentage

server/src/main/java/net/laprun/sustainability/power/PowerResource.java

@@ -21,6 +21,9 @@
 import net.laprun.sustainability.power.persistence.Persistence;
 import net.laprun.sustainability.power.sensors.SamplingMeasurer;
 
+/**
+ * A RESTful endpoint to measure the power consumption associated with processes running on the current system
+ */
 @Path("/power")
 public class PowerResource {
     @Inject
@@ -31,6 +34,12 @@ public void onStartup(@Observes StartupEvent event) {
                 "\nDetected metadata:\n" + metadata());
     }
 
+    /**
+     * Streams power consumption measures associated with the specified process id, if such process is currently running on the system.
+     * @param pid the process identified for which we want to stream measures
+     * @return a stream of {@link SensorMeasure}
+     * @throws Exception if an error occurred while measuring the power consumption
+     */
     @GET
     @RestStreamElementType(MediaType.APPLICATION_JSON)
     @Path("stream/{pid}")
@@ -42,6 +51,12 @@ public Multi<SensorMeasure> streamMeasuresFor(@PathParam("pid") String pid) thro
         }
     }
 
+    /**
+     * Starts measuring the power consumption of the specified application as identified with the specified name and process id
+     * @param appName the application name, used to correlate several measures across different runs
+     * @param pid the process id associated with the current run of the application
+     * @throws Exception if an error occurred while measuring the power consumption
+     */
     @POST
     @Path("start/{appName}/{pid}")
     public void startMeasure(@PathParam("appName") String appName, @PathParam("pid") String pid) throws Exception {
@@ -52,18 +67,31 @@ public void startMeasure(@PathParam("appName") String appName, @PathParam("pid")
         }
     }
 
+    /**
+     * Retrieves the metadata associated with the power sensors of the underlying platform
+     * @return the {@link SensorMetadata} associated with the platform's sensors
+     */
     @GET
     @Path("metadata")
     public SensorMetadata metadata() {
         return measurer.metadata();
     }
 
+    /**
+     * Retrieves the currently used sampling period
+     * @return the sampling period
+     */
     @GET
     @Path("sampling")
     public Duration samplingPeriod() {
         return measurer.samplingPeriod();
     }
 
+    /**
+     * Retrieves all recorded measures associated with the specified application
+     * @param appName the application identifier as provided to {@link #startMeasure(String, String)}
+     * @return the chronological list of measures associated with the specified application
+     */
     @GET
     @Path("measures/{appName}")
     public List<SensorMeasure> measures(@PathParam("appName") String appName) {