TdlModule
name 			gpbdoc
package			org.dmd.gpb.tools.generation.doc.html
templateFile	gpbdoc
commentFormat	<!-- ::comment:: -->
description		These Sections and their associated Templates are used to format HTML
 documentation pages for dark-matter Google Protocol Buffer (GPB) definitions.

TextualArtifact
name 			GpbHtmlDoc
contains		static DocType
contains		static HtmlContent
description 	The GpbHtmlDoc interface defines the overall form of a GPB documentation page.

Section
name			DocType
description		Standard front matter for an XHTML document.

Section
name			HtmlContent
contains		static HtmlHead
contains		static Body
endsWithText	</html>
description		The main html content.

Section
name			HtmlHead
value			styleSheet	"The name of the CSS style sheet to use."
value			moduleName	"The name of the dark-matter GPB module."

Section
name			Body
startsWithText	<body> <div class="center">
contains		static DivHeader
contains		static DivMain
endsWithText	</div> </body> 
description		The body of the document.

Section
name			DivHeader
description		Colored bar across the top

Section
name			DivMain
startsWithText	<div id="main">
contains		static DivContent
endsWithText	</div> <!-- main -->
description		Contains the main content of the page.

Section
name			DivContent
startsWithText	<div id="content">
contains		static ModuleHeader
contains		static DivSummary
contains		static DivDetails
endsWithText	</div> <!-- content -->

Section
name			ModuleHeader
contains		one DescriptionSection
value			moduleName 			"Just the name of the module"
//value			moduleDescription	"The description of the module"
//value			version				"The version at which the module was introduced"

Section
name			DivSummary
startsWithText	<div class="summaryDiv">
contains		static	DivSeparator
contains		many 	SummarySection
endsWithText	</div> <!-- summaryDiv -->

Section
name			DivSeparator
value			title "The tile text to be placed in the separator region"
description		Just a separator area.

Section
name			DivDetails
startsWithText	<div class="details">
// contains		static	DivSeparator
contains		one 	EnumerationSection
contains		one 	MessageSection
contains		one		FieldDetailSection
endsWithText	</div> <!-- details -->


///////////////////////////////////////////////////////////////////////////////
// Summary formatting

Section
name			SummarySection
startsWith		SummaryHeader
contains		many SummaryItem
endsWith		SummaryFooter

Section
name			SummaryHeader
value			summaryTitle		"The items being summarized"
description		The table heading section for a summary.

Section
name			SummaryItem
description		A reference to some item defined in the current module.
value			itemName		"The name of the summary item"
value			hint			"A short description of the item"
value			version			"The version when something was introduced"
value			obsolete		"The version when something became obsolete"

Section
name			SummaryFooter
description		The table closure for a SummarySection.

///////////////////////////////////////////////////////////////////////////////

Section
name			EnumerationSection
startsWithText	<div class="enumerations">
contains		static	DivSeparator
contains		many 	EnumerationDetails
endsWithText	</div> <!-- enumerations -->

Section
name			EnumerationDetails
startsWith		DetailStart
contains		one 	DetailTitle
contains		one		DescriptionSection
contains		one		ValueSection
endsWith		DetailEnd
description		Provides all the details of an enumeration.

Section
name			DetailStart

Section
name			DetailTitle
value			title		"The name of some definition."
value			type		"The type of definition e.g. enum, message etc."
description		Just the title.

Section
name			ValueSection
startsWith		ValueSectionStart
contains		many EnumerationValue
endsWith		ValueSectionEnd

Section
name			ValueSectionStart

Section
name			EnumerationValue
description		The details of a particular enumeration value.
value			valueName		"The name of the enumeration value"
value			value			"The numeric enumeration value"
value			hint			"A short description of the value"
value			version			"The version when the enum value was introduced"
value			obsolete		"The version when the enum value became obsolete"

Section
name			EnumerationFooter
description		The table closure for a EnumerationDetails section.

Section
name			ValueSectionEnd

Section
name			DetailEnd



///////////////////////////////////////////////////////////////////////////////

Section
name			MessageSection
startsWithText	<div class="messages">
contains		static	DivSeparator
contains		many 	MessageDetails
endsWithText	</div> <!-- messages -->

Section
name			MessageDetails
startsWith		DetailStart
contains		one	DetailTitle
contains		one DescriptionSection
contains		one FieldSection
endsWith		DetailEnd
description		Provides all the details of a message.

Section
name			FieldSection
startsWith		FieldSectionStart
contains		many FieldReference
endsWith		FieldSectionEnd

Section
name			FieldSectionStart


Section
name			FieldReference
description		The details of a field used in a message.
value			icon			"The icon representing required, optional, repeated"
value			tooltip			"The tool tip text for the icon"
value			fieldRef		"The href of the field being referenced"
value			fieldName		"The name of the field being referenced"
value			generateAs		"The name the will be used in the generated .proto file"
value			typeRef			"A link to the type of the field"
value			typeName		"The name of the type"
value			fieldTag		"The numeric tag for the field"
value			hint			"A short description of the value"
value			version			"The version when the enum value was introduced"
value			skip			"Any versions where this field is skipped"
value			obsolete		"The version when the enum value became obsolete"

Section
name			FieldSectionEnd

///////////////////////////////////////////////////////////////////////////////

Section
name			FieldDetailSection
startsWithText	<div class="fields">
contains		static	DivSeparator
contains		many 	FieldDetails
endsWithText	</div> <!-- fields -->

Section
name			FieldDetails
startsWith		DetailStart
contains		one	DetailTitle
contains		one DescriptionSection
// contains		one FieldSection
endsWith		DetailEnd
description		Provides all the details of a field.


///////////////////////////////////////////////////////////////////////////////



Section
name			DescriptionSection
startsWith		DescriptionStart
contains		many	AttributeInfo
contains		many	DescriptionExtension
endsWith		DescriptionEnd
description		Provides an area to describe something.

Section
name			DescriptionStart
description		Starts the div and the table to hold the attribute info.

Section
name			AttributeInfo
value			label	"A label for the information"
value			info	"The actual information"
description		These are just rows in a table.

Section
name			DescriptionEnd
description		Closes the table and the div.


ExtensionHook
name				DescriptionExtension
usesSection			AttributeInfo
targetObjectClass	org.dmd.gpb.server.extended.GpbDefinition
description			This hook allows you to include additional description information
 on any GpbDefinition that's formatted by the GpbDocGenerator.


