How to add to Doxygen

How to add to our Doxygen docu

In general

The docu consists of auto-generated content from the parsed scripts and additional pages on various topics. To support the duty is good practice as a developer, so:

• MUST: Comment your code with Doxygen-compatible syntax ( -> have a look at existing code).
• OPTIONAL: Create your own so-called 'Related pages' (this is one of them) to describe overall concepts or details you don't want to explain in your class documentation via above-mentioned comments.

If you updated the master branch with new documentation, think about pushing the generated html files to the root of the repo hosting the docu here.

Note: We are currently using Doxygen Version 1.8.13 for Windows. Other versions may have queer effects as each version tends to have their own quirks...

Documentation structure

Regarding the project (game feature) content itself, there are distinct steps from an idea, to its evaluation/integration on system level, to its realization on SW level. This is explained on the SW Component Design pages.
The resulting SW has to be documented as well, which is done in the SW Architecture and the generated SW detailed design (API). Additionally, there should be pages on development topics, such as tooling and How-Tos.

Modifying a page

You can change the Markdown content with any text editor. Some editors, like VS Code, are able to show rendered previews of the Markdown, which gives a hint for how it's going to look as Doxygen output as well.

When adding or modifying content of pages, consider to build the docu afterwards locally, to check whether the result matches your expectations. Also consider uploading the HTML output (in Doc/doxy_out) to our Docu repository: https://github.com/TheRoot89/BomberUnitsDocu
You do not have to create a branch or anything, simply commit your new docu generated content to the master.

Creating a new page

Ok, so assuming you want to explain a concept, do a How-to or whatever comes to your mind - and you need to add a new page:

1. Create a new .md file and add it somewhere reasonable in Doc/doxy_in/docs_doxygen.
   Should you want to check in any files Doxygen cannot parse but you for example want to provide a link to it, add those to Doc/doxy_in/docs_non_doxygen.
2. Give the file a header on the first line like this: \page [page_tag] [page title]
3. Add some content to the page, typically using the double-underline to mark the main title.
4. Add your page to the navigation tree by making it the child of a reasonable parent page. This is done by adding the \subpage [page_tag] command somewhere on the parent page.
   You have to make your page a child of another, otherwise the new page will appear on the top level of the navigation tree to the left.
5. Add references to your page from other pages or from code if you like: \ref [page_tag]

At the positions of references and \subpage commands Doxygen will place the page title (may contain spaces) you also defined on the first line.

Note: In case you are reading this as a text file: the commands only use a single backslash: "\". The second one is an escape character for writing this without invoking the command.

Using PlantUML graphs in Markdown files

PlantUML provides a syntax to specify UML graphs inline from Markdown. The result is rendered here in the preview and in Doxygen. Writing PlantUML with the following Syntax will generate it in the VSCode preview, but also show the initial, quite ugly code block ticks in Doxygen. This is unfortunate but I found no workaround yet. Also the set style configuration file is not included when previewing.

An example for a PlantUML activity diagram:

~~~plantuml

~~~

Using images in Doxygen

To import an image file use the command . Again, without any backslashes, should you be reading this in plain text.

Your have to give the path relative to the Doc folder as this is the execution directory for Doxygen. Also, you have to place your images in the doxy_in/images folder, so your path will be: /doxy_in/images/[image_file]

Example image

Please note images will usually not be found and displayed in the markdown preview.

---

readme_scripts_visualsAndEffects