X3D node and field documentation is now available in the API docs

Posted on

You can now find a node in the engine Pascal reference, like TTransformNode, and:

  • the Pascal description will include a short summary of node’s purpose,
  • and the important properties (like Translation, Center, etc.) are visible,
  • and (with time…) the properties will be documented too.

To make this prominent, we also link to it from our X3D components description (grouping component, for Transform node) (by “API reference” links). I want to emphasize this way that you can build and modify the X3D graph at runtime, which is a way to do many cool things with the engine:) Simple example of it is in the tutorial.

To make it possible:

  • We have added previous node “helpers” (like “TTransformNode.Translation” helper, wrapping an internal “TTransformNode.FdTranslation”) as normal class properties. This was done by generating files inside the src/x3d/auto_generated_node_helpers/ .

  • The node’s descriptions are specified directly in the src/x3d/x3dnodes_standard_xxx.inc files.

  • The field’s descriptions are specified inside the src/x3d/x3dnodes_documentation.txt . It is added to the documentation using the PasDoc feature https://github.com/pasdoc/pasdoc/wiki/ReadDescriptionFromFile .

This is of course an ongoing effort, and help in documenting is most welcome!:) Be sure to consult with X3D specification and with our docs to document everything correctly:)

In the future: we *may* add some stuff automatically from X3D Tooltips (but they are not always as concise, or as good, as we would like).

Also in the future: we definitely will gradually hide the somewhat-internal properties FdXxx (first we’ll hide them from docs, and then we may just make them private). In most cases, users should not use them. But not everything yet has the non-FdXxx equivalent, in particular multiple-valued fields don’t have them yet, like FdGrouping.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.