ConfigDoc

Description

sealed class Tinman.Core.Config.Docs.ConfigDoc

Derived from

SerializableBase abstract
IValidatable
ICollector<TypeDocNode>

Defines documentation content for ConfigTypes.

The workflow for authoring config documentation looks like this:

  1. Author an XML file that contains the documentation content.

  2. Use Generate to compile a BCD file from the XML file.

  3. Use Load1 to load an external BCD file at runtime.

Alternatively, the following code-based workflow may be used:

  1. Create MemberDocNode objects and populate with IBlockNode content.

  2. Create TypeDocNode objects and populate with IBlockNode content and MemberDocNode objects.

  3. Create a ConfigDoc object for a specific TinmanModule and populate with TypeDocNode objects.

  4. Optionally use Save1 to write a BCD file (see first workflow).

Public / Constructors

Config​Doc

public constructor ConfigDoc → (1)

module in : TinmanModule

[not-null]
The module.

Creates a new instance of ConfigDoc.

Public / Methods

Generate

public static method Generate → (2)

input in : Path

[not-null]
Path to the input documentation content XML file.

output opt : Path = null

Path to the output documentation content BCD file. If null, input in will be used, having its suffix replaced with .bcd. If Path.Unknown, only the input input in is validated and no BCD file is generated (its output path is still returned, though).

returns → Path

The path to the generated BCD file.

Builds a config documentation file (*.BCD) from the given XML content.

The documentation content XML must be compatible with this DTD:

<!ELEMENT documentation (type*)>

<!ATTLIST documentation guid CDATA #IMPLIED>

<!ELEMENT type (text, field*)>
<!ATTLIST type name CDATA #REQUIRED>

<!ELEMENT field (text*) >
<!ATTLIST field name CDATA #REQUIRED>

<!ELEMENT text (#PCDATA|p|b|i|c|a|br|hr|ul|ol)*>
<!ATTLIST text lang CDATA #REQUIRED>

<!ELEMENT a EMPTY>
<!ATTLIST a href CDATA #REQUIRED>

<!ELEMENT p (#PCDATA|b|i|c|a|br)*>
<!ELEMENT b (#PCDATA)>
<!ELEMENT i (#PCDATA)>
<!ELEMENT c (#PCDATA)>
<!ELEMENT br EMPTY>
<!ELEMENT hr EMPTY>
<!ELEMENT ul (li*)>
<!ELEMENT ol (li*)>
<!ELEMENT li (#PCDATA|p|b|i|c|a|br|ul|ol)*>

Use this to associate an XML file with the DTD:

<!DOCTYPE documentation PUBLIC "-//TINMAN//CONFIGDOC//EN" "https://dtd.tinman3d.com/ConfigDoc.dtd">

The type and field elements are loaded into TypeDocNode and MemberDocNode objects and added to an intermediate ConfigDoc object, which is then saved to a BCD file. The trimmed inner XML content of text can be passed to DocumentUtil.BlockContent, in order to produce IBlockNode content objects.

IOException

If an I/O error has occurred.

ValidatingException

If the XML content is malformed.

See also

ConfigDocAction

Get

public method Get → (1)

name in : string

[not-null]
The type name.

returns → TypeDocNode

The documentation or null.

Returns the documentation for the given type.

Load

2 overloads

public static method Load1 → (1)

path in : Path

[not-null]
The file to load.

Loads the given config documentation file (*.BCD).

IOException

If an I/O error has occurred.

See also

TinmanModule.ConfigDocumentation

public static method Load2 → (1)

stream in : IDataStream own

[not-null]
The data to load.

Loads the given config documentation file (*.BCD).

IOException

If an I/O error has occurred.

See also

TinmanModule.ConfigDocumentation

Save

2 overloads

public method Save1 → (1)

path in : Path

[not-null]
The file to save.

Saves this config documentation to a file (*.BCD).

IOException

If an I/O error has occurred.

public method Save2 → (1)

stream in : IDataStream

[not-null]
The file stream.

Saves this config documentation to a file (*.BCD).

IOException

If an I/O error has occurred.

Public / Attributes

Module​Guid

public attribute ModuleGuid → (get)

value : GUID

The module identifier.

Returns the module identifier.

See also

TinmanModule.Guid

Type​Docs

public attribute TypeDocs → (get)

value : IBagConst<TypeDocNode>

[not-null]
The TypeDocNode objects.

Returns the type documentation content.

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.

Serialization

Serial​Id

public static readonly attribute SerialId → (ISerialTypeInfo)

Serialization information about this type.