Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

iox-#1293 Document workaround for documentation in internal headers #2250

Merged
merged 1 commit into from
Apr 14, 2024
Merged

iox-#1293 Document workaround for documentation in internal headers #2250

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions doc/aspice_swe3_4/swe_docu_guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,12 @@ In iceoryx are also custom tags used for extended documentation like errors.
- `/// @min` , use a type safe implementation if possible!
- `/// @max` , use a type safe implementation if possible!

### Include Additional Header Into Documentation

In some cases, the implementation of a component is is placed in an internal folder and the header in the public folder acts as a trampoline with some using declarations.
elBoberido marked this conversation as resolved.
Show resolved Hide resolved
The iceoryx endpoints like `Publisher`, `Subscriber`, etc. are such examples where the public header only includes a using declaration to the actual implementation.
In order to include the documentation of these components, the header containing the documentation can be added to the `INCLUDE_DIR_AND_ADDITIONAL_FILES` list in the CMakeLists.txt.

### Doxygen Generation
For generating the documentation out of the code is CMake in combination with doxygen used.
In iceoryx_meta is a build flag `BUILD_DOC` defined which generates for you the html, xml and latex documentation. There is no need to build iceoryx beforehand.
Expand All @@ -92,6 +98,7 @@ The generated pdf files are generated into `build/doc`. Please note that iceoryx
Generally, you will not find any Doxygen file in our repo because we let CMake generate it.
In [Cmake](CMakeLists.txt) is the command `doxygen_add_docs` which does the job.
There, we are also setting some parameters and the aliases for the custom tags. Aliases with an `xrefitem` create a page where all occurrences of the corresponding tag are collected.

### file header
Please see [Header](../../CONTRIBUTING.md#header).

Expand Down
1 change: 1 addition & 0 deletions doc/website/release-notes/iceoryx-unreleased.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -219,6 +219,7 @@
- Remove hash from the branch names [\#1530](https://github.com/eclipse-iceoryx/iceoryx/issues/1530)
- Automate check for test cases to have UUIDs [\#1540](https://github.com/eclipse-iceoryx/iceoryx/issues/1540)
- Add Thread Sanitizer to build and test workflow [\#692](https://github.com/eclipse-iceoryx/iceoryx/issues/692)
- Document workaround for documentation in internal headers [#1293](https://github.com/eclipse-iceoryx/iceoryx/issues/1293)

**New API features:**

Expand Down
Loading