Adjust documentation according to Dart style guide & mkdocs admonitions

[stefan-brus-frequenz]

What's needed?

The documentation should be adjusted according to:

• https://dart.dev/effective-dart/documentation
• https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types

Proposed solution

Here is a draft on how to adjust the protobuf specification.

// Frequenz Dispatch Automation API
//
// This API automates the process of electricity dispatches for microgrids, streamlining 
// the complex task of electricity dispatching to manage local electricity supply 
// and demand efficiently.

// !!! note
// The primary audience for this API includes application developers in the 
// energy sector focusing on microgrid electricity flow optimization.
//

// ... (rest of the general comments remain unchanged)

// Service providing operations for dispatching electricity to microgrid components.
service MicrogridDispatchService {
  // Lists all existing dispatches.
  rpc ListMicrogridDispatches(DispatchListRequest) returns (DispatchList);
  
  // Creates a new dispatch.
  rpc CreateMicrogridDispatch(DispatchCreateRequest) returns (google.protobuf.Empty);

  // ... (rest of the rpcs remain unchanged)
}

// Represents a single electricity dispatch.
//
// !!! note
// All timestamps are in UTC. Microgrids must translate UTC to local timezones.
//
message Dispatch {
  // Identifier for the dispatch.
  uint64 id = 1;

  // Identifier for the microgrid involved in this dispatch.
  uint64 microgrid_id = 2;

  // Type of the dispatch, user-defined.
  // Downstream applications should understand and process this field accordingly.
  string type = 3;

  // ... (rest of the fields remain unchanged)
}

// ... (rest of the messages remain unchanged)

// Defines the rules for when and how a dispatch should re-occur.
//
// !!! note
// Timestamps are in UTC. It's each microgrid's responsibility to translate UTC to its local timezone.
//
message RecurrenceRule {
  // Frequency specifier of the recurring dispatch.
  Frequency freq = 1;

  // ... (rest of the fields remain unchanged)
}

// ... (rest of the messages remain unchanged)

Use cases

Correct documentation creation with mkdocs and following a unified standards.

Alternatives and workarounds

No response

Additional context

No response