As a seasoned Cursor enthusiast, today I want to share an interesting practical case – using Cursor to create an automated documentation generation system.
Zhuge Liang: “My dear, I heard you have been troubled by writing documentation recently?”
Ma Su: “Yes, strategist, writing API documentation takes a lot of time, and there are often omissions, which is really frustrating.”
Zhuge Liang: “Why not try using Cursor to solve this problem? Let me show you the power of this tool.”
Let’s create a simple API function:
def calculate_order_total(items, discount=0):
"""
Calculate the total order amount
Args:
items (list): A list of products, each product is a dictionary containing name and price
discount (float): Discount rate, range 0-1
Returns:
float: Final order amount
"""
total = sum(item['price'] for item in items)
return total * (1 - discount)
Ma Su: “Wow, this function’s comments are really clear! But having to write such documentation by hand every time is too tiring, right?”
Zhuge Liang: “Watch closely, let Cursor help us automatically generate the documentation comments. Just place the cursor on the function definition line and press Ctrl + I, Cursor will automatically analyze the function structure and generate a comment template.”
Now let’s look at a more complex example:
class OrderManager:
def process_order(self, order_id: str, user_info: dict, payment_method: str) -> dict:
"""
Process user orders
Args:
order_id (str): Unique identifier for the order
user_info (dict): User information, including name, address, etc.
payment_method (str): Payment method, optional values: 'alipay'/'wechat'/'card'
Returns:
dict: Order processing results
success (bool): Whether the processing was successful
message (str): Processing result information
order_status (str): Order status
Raises:
ValueError: When payment_method is not in the supported range
OrderNotFound: When the order ID does not exist
"""
# Processing logic
pass
Ma Su: “That’s amazing! This comment is so detailed, it even specifies exceptional cases!”
Zhuge Liang: “Not only that, Cursor can also help us automatically generate documentation for the entire class. Let me demonstrate how to generate complete API documentation.”
We can use the following command to generate documentation in markdown format:
def generate_api_docs(module_path: str):
"""Generate API documentation using <strong>Cursor</strong>"""
with open(module_path, 'r') as file:
content = file.read()
# Call <strong>Cursor</strong> API to generate documentation
# Press Ctrl + Shift + P, type "Generate Documentation"
Ma Su: “Strategist, where will the generated documentation be saved?”
Zhuge Liang: “Cursor will create a docs folder in the project root directory and organize the documentation structure by module. Let’s take a look at the final result:
# OrderManager API Documentation
## Class Description
Core business logic related to processing orders
## Method List
### process_order
Process user orders...
[Detailed documentation content]
Ma Su: “I learned something! But if the code is updated, how do we keep the documentation in sync?”
Zhuge Liang: “Good question! We can configure an automated workflow:
name: API Documentation
on: [push]
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Generate API docs
run: python generate_docs.py
This way, every time code is submitted, the documentation will be automatically updated.
Ma Su: “So writing documentation can be this easy! Thank you for your guidance, strategist.”
Zhuge Liang: “Make good use of tools for better efficiency. Remember, good documentation not only helps others understand the code but is also an important means of improving code quality.”
Through this example, we have seen the powerful ability of Cursor in automated documentation generation. It can not only generate standardized function comments but also build a complete API documentation system. For developers pursuing efficiency, this is undoubtedly an essential tool.
