Generalize Energy Message Documentation for Broader Market Use

[thomas-nicolai-frequenz]

What's needed?

The Energy message is being used everywhere in our APIs and is mostly related to trading but in various markets like ancillary service markets alongside spot markets. We need to make this more general.

Summary of Changes:

Generalized the Documentation:

• Removed specific references to "trading orders" to make the Energy message applicable across various markets, including ancillary service and spot markets.
• Clarified the Note: Updated the note to emphasize the use of MWh as a consistent unit of energy across various applications, not limited to trading.
• Updated Message Description: Modified the description to represent a unit of energy in a more general context.

This change ensures that the Energy message documentation is universally applicable across all areas where it's used in our APIs.

Proposed solution

// Frequenz definitions of energy.
//
// Copyright 2023 Frequenz Energy-as-a-Service GmbH
//
// Licensed under the MIT License (the "License");
// you may not use this file except in compliance with the License.

syntax = "proto3";

package frequenz.api.common.v1.market;

import "frequenz/api/common/v1/types/decimal.proto";

// Represents a unit of energy.
//
// !!! note
//     The energy unit is denominated in MWh (Megawatt-hours), which is a unit of
//     energy representing total output over a period. This differs from MW
//     (Megawatts), a unit of power that represents the rate of energy production
//     or consumption. Using MWh allows for consistent measurement across various
//     markets and applications.
message Energy {
  // Energy amount in Megawatt-hours (MWh).
  frequenz.api.common.v1.types.Decimal mwh = 1;
}

Use cases

No response

Alternatives and workarounds

No response

Additional context

No response

[thomas-nicolai-frequenz]

Here is also a diff:

--- Original Protobuf File
+++ Updated Protobuf File
@@ -1,6 +1,6 @@
-// Frequenz definitions of energy for electricity trading.
+// Frequenz definitions of energy.
 //
 // Copyright 2023 Frequenz Energy-as-a-Service GmbH
 //
 // Licensed under the MIT License (the "License");
 // you may not use this file except in compliance with the License.
@@ -10,11 +10,12 @@
 package frequenz.api.common.v1.market;

 import "frequenz/api/common/v1/types/decimal.proto";

-// Represents a single unit of electricity.
+// Represents a unit of energy.
 //
 // !!! note
-//     In these trading orders, the unit of energy is denominated in MWh
-//     (Megawatt-hours) as opposed to MW (Megawatts).  MWh is a unit of energy
-//     representing total output over a period, while MW is a unit of power that
-//     represents the rate of energy production or consumption.
+//     The energy unit is denominated in MWh (Megawatt-hours), which is a unit of
+//     energy representing total output over a period. This differs from MW
+//     (Megawatts), a unit of power that represents the rate of energy production
+//     or consumption. Using MWh allows for consistent measurement across various
+//     markets and applications.
 message Energy {
-   // Represents energy unit in Megawatthours (MWh).
+   // Energy amount in Megawatt-hours (MWh).
   frequenz.api.common.v1.types.Decimal mwh = 1;
 }

@camille-bouvy-frequenz please adjust how you see fit.

[camille-bouvy-frequenz]

Done in #267