eclipse-score / eclipse-score/communication
Improvement: Use markers in tutorial code
- Dominant language
- C++
- Stars
- 62
- Forks
- 97
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 72
Description
### What
Currently we use `literalinclude` in the README.rst of our tutorial chapters, which refrnce to code sections, which shall be cited via line-numbers.
This is brittle: Whenever we change the code, the RST-file (code include) gets inconsistent.
SPHINX RST also supports tag-referencing!
We had already to fix such issues: see https://github.com/eclipse-score/communication/pull/1056
E.g.:
```
// [subscription-state-change-handler-start]
auto set_handler_result = proxy_2.message.SetSubscriptionStateChangeHandler(
[handler_state](score::mw::com::SubscriptionState new_state) noexcept {
std::cout << "[proxy_2 handler] Subscription state changed to: " << ToString(new_state) << std::endl;
handler_state->store(new_state, std::memory_order_relaxed);
return true;
});
// [subscription-state-change-handler-end]
```
```
.. literalinclude:: consumer/consumer.cpp
:language: cpp
:start-after: [subscription-state-change-handler-start]
:end-before: [subscription-state-change-handler-end]
:caption: consumer/consumer.cpp
```
The tutorial shall be refactored to use this tag-referencing.
### How
See above.
### Estimates for realization
1 day
### Category
- [ ] Affects Detailed Design
### Requirements / Architecture
- [x] Requirements / Architecture are not affected by this change?
Contributor guide
Research direction
Start with the README.rst files in the tutorial chapters and compare their literalinclude directives with the referenced C++ examples, such as consumer/consumer.cpp. Review the existing marker example and the related pull request, then update the tutorial includes to use tag references. Done means the tutorial consistently uses markers and its code references remain correct after code changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100