YAML templates#
Below, templates to write docstrings of tudat and tudatpy objects are provided.
Note
It is assumed that the reader is familiar with the content of the page about How to write docstrings.
Enumerations#
Note
This template was adapted from the docstrings of the RadiationPressureType enum (see it on Github),
therefore it refers to environment settings objects. However, its content can be adapted to other base classes.
Legend:
<XXX>= name of the enumeration<memberXName>= member number X of the enumeration
Show template
enums:
# py::enum_<XXX>
# enum XXX
- name: <enumPythonName>
short_summary: "What this enum is about"
members:
- name: <member1Name>
- name: <member2Name>
- ...
Classes#
Base class#
Note
This template was adapted from the docstrings of the EphemerisSettings class (see it on Github),
therefore it refers to environment settings objects. However, its content can be adapted to other base classes.
Legend:
<XXX>= class name<pyattribute_1>= some attribute of class, which via the get/set cpp functions is exposed as a class property in python<pytype_1>= type of<pyattribute_1><description_1>= brief description of<pyattribute_1><pyattribute_2>= …
Show template
classes:
- name: <XXX>Settings
short_summary: "Base class for providing settings for <XXX> model."
extended_summary: |
Functional (base) class for settings of <XXX> models that require no information in addition to their type.
<XXX> model classes requiring additional information must be created using an object derived from this class.
attributes: # [py] note: attributes for python only!
# note that <attribute_1> is read/write because tudatpy has get/reset functions for <attribute_1> (documented under methods).
- name: <attribute_1> # [py]
type: <pytype_1> # [py]
description: <description_1> # [py]
# note that <attribute_2> is readonly because tudatpy has only a get functions to access <attribute_2> (documented under methods).
- name: <attribute_2> # [py] readonly
type: <pytype_2> # [py]
description: <description_2> # [py]
- ...
methods:
# list the constructor as first method - python constructor docstrings no longer needed, since constructor will be removed from exposure.
# note that no parameters are given to discourage direct use of constructor (see **** classes and factory functions ****)
- name: ctor # [cpp]
short_summary: "Constructor." # [cpp]
extended_summary: "Instances of this class are typically not generated by the user. Settings objects for XXX models should be instantiated through the factory functions of a derived class." # [cpp]
# now get/set methods of cpp class:
- name: get<attribute_1> # [cpp]
short_summary: "Retrieve <attribute_1>." // if <cpptype_1> is bool use phrase: "Check whether ..." # [cpp]
extended_summary: "Function to retrieve <attribute_1>." // if <cpptype_1> is bool use phrase: "Function to retrieve boolean that..." # [cpp]
# parameters: there are no parameters in getter functions
returns: # [cpp]
- type: <cpptype_1> # [cpp]
description: <description_1> # [cpp]
- name: reset<attribute_1> # [cpp]
short_summary: "Reset <attribute_1>." // if <cpptype_1> is bool use phrase: "Set whether ..." # [cpp]
extended_summary: "Function to reset <attribute_1>." // if <cpptype_1> is bool use phrase: "Function to set boolean that denotes whether ..." # [cpp]
parameters: # [cpp]
- name: <attribute_1> # [cpp]
type: <cpptype_1> # [cpp]
description: <description_1> # [cpp]
returns: there is no return in setter functions
- name: get<attribute_2> # [cpp]
short_summary: "Retrieve <attribute_2>." // if <cpptype_2> is bool use phrase: "Check whether ..." # [cpp]
extended_summary: "Function to retrieve <attribute_2>." // if <cpptype_2> is bool use phrase: "Function to retrieve boolean that..." # [cpp]
parameters: there are no parameters in getter functions
returns: # [cpp]
- type: <cpptype_2> # [cpp]
description: <description_2> # [cpp]
Derived class#
Note
This template was adapted from the docstrings of the DirectSpiceEphemerisSettings class
(see it on Github),
therefore it refers to environment settings objects. However, its content can be adapted to other derived classes.
Legend:
<XXY>= DirectSpiceEphemeris<XXX>= Ephemeris<xxy>= directSpiceEphemerisSettings (factory function)
Note
Public attributes & methods from the <XXX> base class do not have to be re-documented in derived classes
(they are inherited in the API).
Show template
- name: <XXY>Settings
short_summary: "Class for defining settings of <XXY>."
extended_summary: "`<XXX>Settings` derived class for ephemeris which <minimal description of derived class>."
attributes:
# same scheme as documenting attributes from base class: python only, distinction read/write
methods: python constructor docstrings no longer needed, since constructor will be removed from exposure.
- name: ctor # [cpp]
short_summary: "Constructor." # [cpp]
extended_summary: "Instances of the `<XXY>Settings` class should be created through the `<xxy>` factory function." # [cpp]
# other methods, documented in the same style as in base class
Functions#
Note
This template was adapted from the docstrings of the directSpiceEphemerisSettings factory function
(see it on Github),
therefore it refers to environment settings objects. However, its content can be adapted to other functions.
Legend:
<XXY>= DirectSpiceEphemeris<XXX>= Ephemeris<xxy>= directSpiceEphemerisSettings (FF)
Show template
functions:
- name: < python_name of <xxy> > # [py]
- name: <xxy> # [cpp]
short_summary: "Factory function for creating < brief description of the function that the created object serves >."
extended_summary: |
Factory function for settings object, < brief description of the function that the created object serves >.
< additional info / context, mostly found on tudat-space/API/... website >
This function creates an instance of an `<XXX>Settings` derived `<XXY>Settings` object.
parameters:
- name: <pyparametername_1> # [py]
type: <pytype_1> # [py]
if parameters have a default value --> type: <pytype_1>, default=<default_value> # [py]
- name: <parametername_1> # [cpp]
type: <type_1> # [cpp]
description: <description_1>
- name: <pyparametername_2> # [py]
type: <pytype_2> # [py]
if parameters have a default value --> type: <pytype_2>, default=<default_value> # [py]
- name: <parametername_2> # [cpp]
type: <type_2> # [cpp]
description: <description_2>
- ...
returns:
- type: <XXY>Settings # [py] class name of instantiated object
description: [WIP] # [py] return descriptions are WIP to incorporate whishes from Dominic, which I do not understand yet.
- type: <XXY>Settings # [cpp] class name of instantiated object
description: [WIP] # [cpp] return descriptions are WIP to incorporate whishes from Dominic, which I do not understand yet.