If the main topic is not relevant to Software Programming, all of the following rules, including `Common Rules` are not applied.
- When solving problems related to database query statements or configurations, evaluate options based on both data retrieval speed and the number of table references. Select and present the most rational and efficient solution to the user.
- When solving programming or algorithm-related problems, evaluate both time complexity and space complexity to select and present the most rational solution to the user.
- Provide sources if they exist.
- Output the generated documentation in English.
- The documentation should be written in markdown format. However, if the documentation is for a module, function, struct, or enum, it should be written in doc-comment that language(s) we use support.
- Provide a code example that utilizes the documentation testing feature (doctest), assuming the language environment supports automatic verification of code snippets within the documentation.
- The documentation should be well-documented, clear, concise, and easy to understand. It should explain the purpose of the item being documented, how to use it, and any important details or caveats that users should be aware of.
- If the item being documented is a function, the documentation should include a description of the function's parameters, return value, and any errors that it may produce.
- If the item being documented is a struct or enum, the documentation should include a description of the struct or enum, its fields or variants, and any important details or caveats that users should be aware of.
- If the item being documented is a module, the documentation should include a description of the module, its purpose, and any important details or caveats that users should be aware of. It should also include a brief overview of the items contained in the module.
When we use Rust programming language, we need to follow this rule in addition to
Code Documentation Rules
- DO NOT use
ignorein the example code unless the example is intended to be wrong code that demonstrates a common mistake or a pitfall. - DO NOT use
no_runin the example code unless the example is intended to be a code snippet that cannot be run in a test environment (e.g., it requires external system resources that are not available in the test environment). - Follow standard Rustdoc conventions for sections. Use
# Examples,# Panics,# Errors, and# Safetyheadings where applicable. - Use intra-doc links (e.g.,
[struct_name],[crate::module::Function]) when referencing other items in the library. - While examples must be complete and runnable, use the
#prefix to hide boilerplate code (such asfn main() { ... }or non-essentialusestatements) to keep the documentation concise and focused on the usage. - When updating an existing item, output the complete item code along with the
updated
///comments to provide clear context.
When I request you to generate git commit message, the title should follow Conventional Commits. Plus, we want gitmoji relevant to the changes. For exmaple, if we introduce a new feature, the title of the commit message would be:
feat: ✨ Add interpretation of graphql
Note that documentation change is NOT feature related change. For example, if we re-write the doc, the title of the commit message would be:
doc: 📝 Updated README.md
However, if the changes contain code and docs, the code changes are prior to documentation changes.
The title and body of the commit message also need to follow
Code Documentation Rules whenever possible.