ℹ️ Command Information
Table of content:
Introduction
In Java applications, managing and documenting commands effectively is crucial for both developers and users. The CommandInfo class provides a set of powerful annotations designed to enhance the clarity and usability of command-line interfaces within Java applications. These annotations facilitate comprehensive documentation and streamline the process of defining commands.
By using the annotations provided by CommandInfo, developers can:
Clearly describe the purpose and functionality of each command.
Specify how commands should be used, including the format and required parameters.
Offer detailed explanations and warnings about the command’s behavior and implications.
This approach not only improves code readability and maintainability but also ensures that end-users have access to well-documented commands, reducing the likelihood of errors and enhancing overall user experience.
In this document, we will explore the specific annotations available in the CommandInfo class:
@Descriptionfor providing a brief summary of a command.@Usagefor outlining how the command should be invoked.@LongDescriptionfor offering a detailed explanation of the command’s functionality.
These annotations can be applied to methods or classes that represent commands, enabling you to build a robust and user-friendly command documentation system in your Java applications.
Annotations
1. @Description
The @Description annotation is used to provide a brief description of a command. This description should summarize the purpose or function of the command in a single string.
2. @Usage
The @Usage annotation specifies the usage pattern of a command. It provides a concise string that outlines how the command should be invoked or what parameters are required.
3. @LongDescription
The @LongDescription annotation offers a detailed explanation of a command. This annotation allows for a multi-line description, represented as an array of strings, to provide in-depth information about the command's functionality and usage.
Usage of annotations
Here is code example of how we can use command information
We also could get more information about does description by getting CommandContext#commandInfo. For example
If we want to get CommandInfo for the class itself we should call commandManger.getCommandInfo(commandName);
Managing Multiple Descriptions, Usages, and Long Descriptions
Particularly when dealing with command-line interfaces, there are scenarios where multiple classes might define commands with the same name, or where command classes are extended. The CommandInfo class allows for multiple @Description annotations to accommodate these situations, ensuring comprehensive and accurate documentation.
Why Multiple Descriptions?
Handling Multiple Classes with the Same Command Name
In complex applications, you may encounter multiple classes that define commands with the same name but in different contexts or with different functionalities. The ability to use multiple @Description annotations ensures that each class can provide its own description, making it clear what each version of the command does.
Extending Command Classes
When extending a class that defines commands, the subclass may inherit and modify the behavior of the base class commands. Multiple @Description annotations can be used to document both the inherited and additional functionalities provided by the subclass. This approach helps to differentiate between the base command’s behavior and any new or overridden functionalities introduced in the subclass.
Methods
CommandInfo#getDescriptions: Returns a list ofDescriptionannotations associated with a command.CommandInfo#getUsages: Returns a list ofUsageannotations associated with a command.CommandInfo#getLongDescriptions: Returns a list ofLongDescriptionannotations associated with a command.