fix: improve Dartdoc

Signed-off-by: The one with the braid <[email protected]>

lib/src/utils/commands_extension.dart

@@ -37,7 +37,7 @@ extension CommandsClientExtension on Client {
   }
 
   /// Parse and execute a command on Client level
-  /// - `room`: a [Room] to run the command on. Caan be null unless you execute a command strictly requiring a [Room] to run on
+  /// - `room`: a [Room] to run the command on. Can be null unless you execute a command strictly requiring a [Room] to run on
   /// - `msg`: the complete input to process
   /// - `inReplyTo`: an optional [Event] the command is supposed to reply to
   /// - `editEventId`: an optional event ID the command is supposed to edit
@@ -505,10 +505,11 @@ class RoomCommandException extends CommandException {
 /// This class can be used to provide a default, processable output of commands
 /// containing some generic data.
 ///
-/// When simply sending an event to a room, please ensure not to add the
-/// event ID here but simply use `return` instead. Otherwise clients may not be
-/// able to distinguish between an eventual search result or similar output and
-/// just the default [Room.sendTextEvent] behavior.
+/// NOTE: Please be careful whether to include event IDs into the output.
+///
+/// If your command actually sends an event to a room, please do not include the event ID here. The default behavior of the [Room.sendTextEvent] is to return the event ID of the just sent event. The [DefaultCommandOutput.events] field is not supposed to replace/duplicate this behavior.
+///
+/// But if your command performs an action such as search, highlight or anything your matrix client should display different than adding an event to the [Timeline], you can include the event IDs related to the command output here.
 class DefaultCommandOutput {
   static const format = 'com.famedly.default_command_output';
   final List<String>? rooms;