ThePassionate opened a new pull request, #17997:
URL: https://github.com/apache/nuttx/pull/17997
## Mutex: Correct Documentation for nxmutex_destroy Function
### Summary
This PR corrects the documentation note for the `nxmutex_destroy()` function
in the mutex header file. The previous documentation incorrectly described the
function as initializing the mutex instead of destroying it, causing confusion
about the function's actual behavior and safety considerations.
### Changes
#### Files Modified
1. **include/nuttx/mutex.h**
- Correct the `nxmutex_destroy()` function documentation
- Replace misleading text about initialization with accurate destruction
behavior description
- Clarify that the mutex becomes invalid after destruction and cannot be
used until reinitialized
### Technical Details
**Issue:**
- The documentation for `nxmutex_destroy()` incorrectly described the
function as initializing the mutex
- This caused confusion about the function's actual purpose (destroying the
mutex)
- Missing important information about post-destruction behavior and
requirements
**Solution:**
- Update the documentation to accurately describe the destroy operation
- Clarify that after destruction, the mutex is no longer valid
- Document that the mutex must not be used until reinitialized with
`nxmutex_init()`
- Improve clarity regarding safety considerations in OS context
**Changes:**
- Old: "This function initializes the UNNAMED mutex..."
- New: "This function destroys the specified mutex. After a successful call,
the mutex is no longer valid and must not be used..."
### Impact
- **Documentation**: Improves accuracy and clarity of API documentation
- **Clarity**: Prevents confusion about mutex lifecycle and destruction
behavior
- **Safety**: Emphasizes important safety considerations after destruction
- **Developer Experience**: Helps developers understand proper mutex usage
patterns
### Testing
Documentation-only change; no functional code changes.
---
**Author**: makejian <[email protected]>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
