example::ExampleDoxygen

Defined in example/ExampleDoxygen.h

class example::ExampleDoxygen

This is a class. The text up to the first empty line is considered the “brief” comment. It can span multiple sentences and lines, much like this comment.

Anything after the first “paragraph” is consider the “detailed” description. This can contain multiple paragraphs and directives.

See Omniverse Doxygen Documentation Guide to see the raw input to this document.

Referencing other entities is done via the @ref directive. For example, the first non-constructor in this class is exampleMethod.

Technically, Doxygen will try to auto-link tokens that match known entities even without @ref. The benefit of using @ref is that if Doxygen can’t find the reference, you’ll get a build time error. As such, the use of @ref is highly encouraged to make sure Doxygen is doing what you think it’s doing.

The full list of Doxygen commands can be found at: https://www.doxygen.nl/manual/commands.html (note: this link was auto-linked).

Public Functions

float *exampleMethod(const char *name, int x, int y, int z)

This is the brief comment for the example method. It’s a nice comment.

We now start the “full” documentation after a blank line.

Docs can have multiple paragraphs. Paragraphs are defined by blank lines. Many small paragraphs (each getting a single point across) are preferred over giant paragraphs. This is technical documentation, not Shakespere.

Parameters are documented with the @param command.

Parameters can be referenced in docs with @p. For example, check out x.

It’s useful to reference other entities in docs. In ExampleDoxygen’s docs, we showed how to use @ref. Another useful command is @see, which creates a special section in the docs.

Doxygen supports a dedicated statement to denote the return value of a function: @returns.

Text markup is a lot like Markdown:

  • Inline Code: `Inline Code`

  • Italics: *Italic*

  • Bold: **Bold**

Right

Center

Left

10

10

10

1000

1000

1000

There are limits to the Markdown like syntax above. When those fail, old-school HTML commands like <i> and <b> can be used.

Code examples can also be embedded. For example:

// use this class as such
auto example = new DoxygenExample;
auto value = example->exampleMethod("i'm an example", 1, 2, 3);

Commands like @see, @returns, and @param should come at the end of the documentation block in order to avoid confusing Doxygen.

See

See myProtectedFunction for another method to call. This was generated with @see.

Parameters

  • name – Name of the thing to pass to the method. Must not be nullptr. This was generated with @param.

  • x, y, z – Multiple parameters can be given the same description by using a ,. This was generated with @param.

Returns

Returns a pointer to a useful float, that totally means something… useful. Could return nullptr if something went wrong, which is likely. This was generated with @returns.

void advancedExampleMethod()

Shows advanced usage of the Omniverse documentation system.

exampleMethod shows vanilla Doxygen. Omniverse adds some other features to Doxygen to better integrate Doxygen with its documentation system.

Use the @thread_safety command to denote the thread safety of an entity.

A block of ReStructuredText can be embedded with @rst and @endrst:

This text is in ReStructuredText, but looks like it’s a part of Doxygen. We’re about to show an admonition.

Tip

ReStructuredText can be added with @ rst and @ endrst.

This text is also in ReStructuredText. It supports links to other ReStructuredText docs like Omniverse Documentation Guidelines.

Inline ReStructuredText can be embedded via @inlinerst and @endrst.

Linking to a ReStructuredText reference is handled with @rstref{}. For example, this is a link to the ReStructuredText document on How to Unlock the Full Power of ReStructuredText . Note, that these links need both the ReStructuredText reference in <> and the text to display (before the <>).

Links to Markdown files can be inserted with @rstdoc{}. For example, to link to repo_docs’s Change Log: CHANGES.md The path given to @rstdoc is relative to the documentation’s build directory, which for repo_docs is _build/docs/repo_docs/latest/. This filename should not contain a file extension.

Thread Safety

Unlike the rest of Omniverse, this method is not thread safe. This was generated with @thread_safety.

Protected Functions

void myProtectedFunction()

Protected functions are included in the Doxygen output.