eclipse-score / eclipse-score/communication

Improvement: Use markers in tutorial code

Open
#1,057 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.