Commits

alfonse  committed 9f22210

Documented the schema.

  • Participants
  • Parent commits 6c10ec4

Comments (0)

Files changed (2)

File Design/ProgDoc.rnc

         pd.codedocs
         
     pd.codedocs =
+        ## The root of the documentation.
         element codedocs { pd.codedocs.attlist, pd.codedocs.content }
     pd.codedocs.content =
         pd.info, 
         pd.codedocs.tool_version.attribute?
 
     pd.info =
+        ## Contains information that pertains to this piece of documentation. 
+        ## This identifies the name of the project that is documented, as well as the version
+        ## of that project.
         element info { pd.info.attlist, pd.info.content }
     pd.info.content = empty
     pd.info.attlist = pd.info.name.attribute, pd.info.version.attribute
     div
     {
         pd.global.container =
+            ## The global container is a special container that differs slightly from the standard
+            ## container. It is only found as a direct child of the root.
+            ## The global container does not have a name attribute, and its kind is always
+            ## "namespace". This allows for easy identification when processing, as all
+            ## other containers must have a name.
+            ##
+            ## All source code is a descendant of the global container. Even languages that
+            ## do not have the concept of a namespace will have the global container.
             element container { pd.global.container.attlist, pd.global.container.content }
         pd.global.container.content = pd.container.content
         pd.global.container.attlist =
             pd.global.container.kind.attribute
             
         pd.container =
+            ## Containers are holders of other constructs within the language. These are language
+            ## objects, so they are defined by the particular language being used. There are
+            ## several different kinds of containers defined in different languages. Containers are
+            ## named, and they can contain other child containers. Containers include
+            ## namespaces, classes, structs, and other similar concepts.
+            ##
+            ## Depending on the type of container, a container can have parent/child relationships
+            ## with other containers. Containers can contain other containers, which is a different
+            ## relationship than parent/child. Members of a namespace are XML children of that
+            ## namespace, while the derived class of a class has an explicit referential
+            ## relationship.
+            ##
+            ## Containers can be documented. If so, then they will have a reference to a 
+            ## "doc" element that contains their documentation.
             element container { pd.container.attlist, pd.container.content }
         pd.container.content =
             pd.container.parent* &
         pd.container.attlist = pd.common.language.attlist, pd.container.kind.attribute
     
         pd.container.parent =
+            ## This identifies a container that is the language parent of this container.
+            ## This differs from being an XML parent. The XML parent of a container is
+            ## the language feature that contains it in the language sense. If this
+            ## container is a member of the namespace "foo", then the direct XML parent of
+            ## this container will be the namespace "foo".
+            ##
+            ## This element instead refers to OOP-style parentage. That is, the base class/interface
+            ## of this object. Some kinds of objects cannot have OOP-style parentage, but this
+            ## depends on the language. The XML element referenced by this element must
+            ## be a container.
+            ##
+            ## This element also specifies the kind of inheritance.
             element parent { pd.container.parent.attlist, pd.container.parent.content }
-        pd.container.parent.content = pd.container.linkage*
+        pd.container.parent.content = pd.container.inheritance*
         pd.container.parent.attlist = pd.common.idref.attribute
         
-        pd.container.linkage =
-            element linkage { pd.container.linkage.attlist, pd.container.linkage.content }
-        pd.container.linkage.content = empty
-        pd.container.linkage.attlist = pd.linkage.kind.attribute
+        pd.container.inheritance =
+            ## This identifies the way in which the derived container is derived.
+            ## Many languages have modifiers on the way that classes/interfaces are derived.
+            ## Public vs protected inheritance, for example. There can be multiple kinds
+            ## of inheritance, which are language-specific.
+            element inheritance { pd.container.inheritance.attlist, pd.container.inheritance.content }
+        pd.container.inheritance.content = empty
+        pd.container.inheritance.attlist = pd.inheritance.kind.attribute
 
         pd.container.child =
+            ## This identifies a container that is derived from this container. The XML
+            ## element referenced by this element must be a container.
             element child { pd.container.child.attlist, pd.container.child.content }
         pd.container.child.content = empty
         pd.container.child.attlist = pd.common.idref.attribute
             
         pd.template_list =
+            ## Some containers or members of containers can be templated. For languages
+            ## that support such things. This element defines the list of template
+            ## parameters.
             element template-list { pd.template_list.attlist, pd.template_list.content }
         pd.template_list.content = pd.template*
         pd.template_list.attlist = empty
 
         pd.template =
+            ## This element represents a single template parameter in the list of template
+            ## parameters. It has a type, possibly a name, and potentially a default value.
             element template { pd.template.attlist, pd.template.content }
         pd.template.content = pd.template.type, pd.template.default?
         pd.template.attlist = pd.common.name.attribute?
         
         pd.template.type =
+            ## This element represents the type of a template parameter.
             element type { pd.template.type.attlist, pd.template.type.content }
         pd.template.type.content = doc.lang_string
         pd.template.type.attlist = empty
     
         pd.template.default =
+            ## This element represents the default value for a template parameter.
             element default { pd.template.default.attlist, pd.template.default.content }
         pd.template.default.content = doc.lang_string
         pd.template.default.attlist = empty
     
         pd.property_list =
+            ## Containers and members can have multiple properties that describe them
+            ## in relation to their parents. These include access classes (public, private, etc),
+            ## inheritance classes (virtual, override, etc), whether the member is a
+            ## constructor or destructor of the container that holds it, and various other things.
+            ## These proerties are described in this list.
             element property-list { pd.property_list.attlist, pd.property_list.content }
         pd.property_list.content = pd.property+
         pd.property_list.attlist = empty
 
         pd.property =
+            ## This represents a single property of a container or member.
             element property { pd.property.attlist, pd.property.content }
         pd.property.content = empty
         pd.property.attlist = pd.property.kind.attribute
         
         pd.member_section =
+            ## Members within a container can be arranged into named sections. These sections can
+            ## be documented with text as well.
             element member_section { pd.member_section.attlist, pd.member_section.content }
         pd.member_section.content = pd.member+
         pd.member_section.attlist = pd.common.language.attlist
     
         pd.member =
+            ## A member is any non-container construct in a language. Members represent
+            ## leaf constructs, like functions, typedefs, etc.
+            ##
+            ## Members can be documented. If so, then they will have a reference to a 
+            ## "doc" element that contains their documentation.
             element member { pd.member.attlist, pd.member.content }
         pd.member.content =
             pd.template_list? &
             pd.common.language.attlist, pd.member.kind.attribute, pd.member.overrides.attribute?
         
         pd.member.type =
+            ## Some kinds of members can have a type. For functions, this represents the return
+            ## type of the function. These can reference a return element in a piece of
+            ## documentation. For variables, this represents the type of the variable.
             element type { pd.member.type.attlist, pd.member.type.content }
         pd.member.type.content = doc.lang_string
         pd.member.type.attlist = pd.common.doc_ref.attribute?
 
         pd.param_list =
+            ## Some kinds of members have parameters. This element lists those parameters.
             element param-list { pd.param_list.attlist, pd.param_list.content }
         pd.param_list.content = pd.param*
         pd.param_list.attlist = empty
     
         pd.param =
+            ## This element represents a parameter in a member. It can reference a particular
+            ## piece of documentation that documents this parameter.
             element param { pd.param.attlist, pd.param.content }
         pd.param.content =
             pd.param.type &
             pd.param.default? &
             pd.param.array?
         pd.param.attlist =
-            pd.param.name.attribute?, pd.common.doc_ref.attribute?
+            pd.common.name.attribute?, pd.common.doc_ref.attribute?
         
         pd.param.type =
+            ## This element represents the type of a parameter within a member.
             element type { pd.param.type.attlist, pd.param.type.content }
         pd.param.type.content = doc.lang_string
         pd.param.type.attlist = pd.common.doc_ref.attribute?
         
         pd.param.default =
+            ## This element defines the default value for a member's parameter.
             element default { pd.param.default.attlist, pd.param.default.content }
         pd.param.default.content = doc.lang_string
         pd.param.default.attlist = empty
     
         pd.param.array =
+            ## This element represents the array specifier for a member's parameter. If the
+            ## array specifier is present but empty, this means that the array specifier is empty.
             element array { pd.param.array.attlist, pd.param.array.content }
         pd.param.array.content = text | empty
         pd.param.array.attlist = empty
     
         pd.enum_value_list =
+            ## This element represents the various enumerators in a member. It should only be present if
+            ## the member has a kind of "enumeration". The order of the enumerators is as defined
+            ## in the original language.
             element enum-value-list { pd.enum_value_list.attlist, pd.enum_value_list.content }
-        pd.enum_value_list.content = pd.enum_value+
+        pd.enum_value_list.content = pd.enumerator+
         pd.enum_value_list.attlist = empty
         
-        pd.enum_value =
-            element enum-value { pd.enum_value.attlist, pd.enum_value.content }
-        pd.enum_value.content = pd.enum.value?
-        pd.enum_value.attlist = pd.common.doced.nofile.attlist
+        pd.enumerator =
+            ## This represents a single enumerator in the enumeration. Enumerators
+            ## can be documented; if they are, they will reference that documentation.
+            element enumerator { pd.enumerator.attlist, pd.enumerator.content }
+        pd.enumerator.content = pd.enum.value?
+        pd.enumerator.attlist = pd.common.doced.nofile.attlist
             
         pd.enum.value =
+            ## This represents the value of a particular enumerator.
             element value { pd.enum.value.attlist, pd.enum.value.content }
         pd.enum.value.content = doc.lang_string
         pd.enum.value.attlist = empty
             (pd.short_doc & pd.long_doc)
     
         pd.short_doc =
+            ## Short-form documentation can be a list of block-level elements, without any section-level
+            ## elements.
             element short-doc { pd.short_doc.attlist, pd.short_doc.content }
         pd.short_doc.content = doc.block_elements+
         pd.short_doc.attlist = empty
         
         pd.long_doc =
+            ## Long-form documentation can store any of the documentation elements.
             element long-doc { pd.long_doc.attlist, pd.long_doc.content }
         pd.long_doc.content =
             (doc.block_elements+, doc.block_section*) |
         pd.long_doc.attlist = empty
 
         pd.doc.file_list =
+            ## This represents a list of the files that the code docs were built from. The
+            ## order of the files is unimportant.
             element file-list { pd.file_doc_list.attlist, pd.file_doc_list.content }
         pd.file_doc_list.content = pd.file.doc+
         pd.file_doc_list.attlist = empty
             
         pd.file.doc =
+            ## The doc element for file documentation. Unlike other doc elements, it does not
+            ## actually have to have documentation. It can contain references to various language
+            ## constructs.
             element doc { pd.file.doc.attlist, pd.file.doc.content }
         pd.file.doc.content =
-            pd.common.doc.content &
+            pd.common.doc.content? &
             doc.programlisting? &
             (pd.container_ref*) &
             (pd.member_ref*) &
         pd.file.doc.attlist = pd.common.doc.attlist
             
         pd.container_ref =
+            ## A reference to a container element.
             element container-ref { pd.container_ref.attlist, pd.container_ref.content}
         pd.container_ref.content = empty
         pd.container_ref.attlist = pd.common.idref.attribute
         
         pd.member_ref =
+            ## A reference to a member element.
             element member-ref { pd.member_ref.attlist, pd.member_ref.content }
         pd.member_ref.content = empty
         pd.member_ref.attlist = pd.common.idref.attribute
         
         pd.sectioned_member_refs =
+            ## A named, documented section that contains references to members.
             element sectioned-member-ref { pd.sectioned_member_refs.attlist, pd.sectioned_member_refs.content }
         pd.sectioned_member_refs.content = pd.member_ref+
         pd.sectioned_member_refs.attlist = pd.common.doced.nofile.attlist
         
         pd.doc.page_list =
+            ## This represents a list of pages of documentation. The order of the list is the
+            ## expected order that the pages will be presented in. Also, the very first page is
+            ## considered special; it is the main page and should be displayed first.
             element page-list { pd.doc.page_list.attlist, pd.doc.page_list.content }
         pd.doc.page_list.content = pd.page.doc+
         pd.doc.page_list.attlist = empty
 
         pd.page.doc =
+            ## The doc element for page documentation. In addition to documentation (long-form), it
+            ## can have a list of sub-page doc elements. These can in turn have other sub-pages. The
+            ## depth-first order of these pages is the expected order of presentation.
             element doc { pd.page.doc.attlist, pd.page.doc.content }
         pd.page.doc.content =
-            pd.common.doc.content &
+            pd.long_doc &
             (pd.page.doc+)
         pd.page.doc.attlist = pd.common.doc.attlist
         
         pd.doc.module_list =
+            ## This represents a list of modules. The order of the list is irrelevant.
             element module-list { pd.doc.module_list.attlist, pd.doc.module_list.content }
         pd.doc.module_list.content = pd.module.doc+
         pd.doc.module_list.attlist = empty
     
         pd.module.doc =
+            ## The doc element for module documentation. In addition to documentation, modules have
+            ## a list of language constructs, files, and pages that are all considered to be direct
+            ## members of that module. The module's documentation is expected to provide an overview
+            ## of these.
+            ##
+            ## Modules also can have a list of child modules. The order of these sub-modules is
+            ## irrelevant.
             element doc { pd.module.doc.attlist, pd.module.doc.content }
         pd.module.doc.content =
             pd.common.doc.content &
         pd.module.doc.attlist = pd.common.doc.attlist
         
         pd.file_ref =
+            ## A reference to a file doc element.
             element file-ref { pd.file_ref.attlist, pd.file_ref.content }
         pd.file_ref.content = empty
         pd.file_ref.attlist = pd.common.idref.attribute
 
         pd.page_ref =
+            ## A reference to a page doc element.
             element page-ref { pd.page_ref.attlist, pd.page_ref.content }
         pd.page_ref.content = empty
         pd.page_ref.attlist = pd.common.idref.attribute
         
         pd.doc.lang_list =
+            ## This represents all of the documentation specifically for language constructs.
+            ## The order is irrelevant.
             element lang-list { pd.doc.lang_list.attlist, pd.doc.lang_list.content }
         pd.doc.lang_list.content = pd.lang.doc+
         pd.doc.lang_list.attlist = empty
         
         pd.lang.doc =
+            ## The doc element for language documentation. In addition to either short or
+            ## long form documentation, it may have a list of references to the language elements
+            ## that it documents.             
             element doc { pd.lang.doc.attlist, pd.lang.doc.content }
-        pd.lang.doc.content = doc.lang.ref*, pd.common.doc.content
+        pd.lang.doc.content = (doc.lang.ref*) & pd.common.doc.content
         pd.lang.doc.attlist = pd.common.doc.attlist
     }
     
             doc.literal |
             doc.superscript |
             doc.subscript |
-            doc.argument |
+            doc.parameter |
             doc.style |
             doc.lang.ref
             
-        doc.inline_data = mixed { doc.inlines* }
+        doc.inline_data =
+            mixed { doc.inlines* }
             
         doc.emphasis =
+            ## The given text should be emphasized in some way.
             element emphasis { doc.emphasis.attlist, doc.emphasis.content }
         doc.emphasis.content = doc.inline_data
         doc.emphasis.attlist = doc.common.inline.attlist
         
         doc.anchor =
+            ## This represents a location in the documentation that can be referenced.
             element anchor { doc.anchor.attlist, doc.anchor.content }
         doc.anchor.content = empty
         doc.anchor.attlist =
             pd.identifier.attribute
         
         doc.literal =
+            ## The given text should be displayed as a literal value. Typically for inline code.
             element literal {doc.literal.attlist, doc.literal.content}
         doc.literal.content = doc.inline_data
         doc.literal.attlist = doc.common.inline.attlist
         
         doc.superscript =
+            ## The given text should have its baseline raised and font shrunken.
             element superscript { doc.superscript.attlist, doc.superscript.content }
         doc.superscript.content = doc.inline_data
         doc.superscript.attlist = doc.common.inline.attlist
     
         doc.subscript =
+            ## The given text should have its baseline lowered and font shrunken
             element subscript { doc.subscript.attlist, doc.subscript.content }
         doc.subscript.content = doc.inline_data
         doc.subscript.attlist = doc.common.inline.attlist
         
-        doc.argument =
-            element argument { doc.argument.attlist, doc.argument.content }
-        doc.argument.content = doc.inline_data
-        doc.argument.attlist = doc.common.inline.attlist
+        doc.parameter =
+            ## The given text represents a function parameter and should be displayed as such.
+            element parameter { doc.parameter.attlist, doc.parameter.content }
+        doc.parameter.content = doc.inline_data
+        doc.parameter.attlist = doc.common.inline.attlist
         
         doc.style =
+            ## The given text should be styled in some special way.
             element style { doc.style.attlist, doc.style.content }
         doc.style.content = doc.inline_data
         doc.style.attlist =
             doc.style.style.attribute
 
         doc.lang.ref =
+            ## A reference to a container, member, or enumerator. The element should be
+            ## replaced by the name of the object it refers to.
             element ref { doc.lang.ref.attlist, doc.lang.ref.content }
         doc.lang.ref.content = empty
         doc.lang.ref.attlist = pd.common.lang_ref.attribute
         
         doc.title =
+            ## The title of a title'd construct.
             element title { doc.title.attlist, doc.title.content }
         doc.title.content = doc.inline_data
         doc.title.attlist = doc.common.inline.attlist
             doc.throw_list
             
         doc.para =
+            ## A paragraph of text. Cannot be nested.
             element para { doc.para.attlist, doc.para.content }
         doc.para.content = doc.inline_data
         doc.para.attlist = doc.common.block.attlist
         
         doc.formal_para =
+            ## A paragraph with title and possible anchor.
             element formal_para { doc.formal_para.attlist, doc.formal_para.content }
         doc.formal_para.content = doc.title, doc.para
         doc.formal_para.attlist = doc.common.block.attlist, pd.identifier.attribute?
 
         doc.note =
+            ## A notation. The contained text should be offset. If it has a title, then the title
+            ## will replace the usual "note" text.
             element note { doc.note.attlist, doc.note.content }
         doc.note.content = doc.title?, doc.block_elements+
         doc.note.attlist = doc.common.block.attlist
 
         doc.important =
+            ## An important notation. The contained text should be offset. If it has a title, then the title
+            ## will replace the usual "important" text.
             element important { doc.important.attlist, doc.important.content }
         doc.important.content = doc.title?, doc.block_elements+
         doc.important.attlist = doc.common.block.attlist
 
         doc.warning =
+            ## A warning. The contained text should be offset. If it has a title, then the title
+            ## will replace the usual "warning" text.
             element warning { doc.warning.attlist, doc.warning.content }
         doc.warning.content = doc.title?, doc.block_elements+
         doc.warning.attlist = doc.common.block.attlist
 
         doc.caution =
+            ## A cautionary note. The contained text should be offset. If it has a title, then the title
+            ## will replace the usual "caution" text.
             element caution { doc.caution.attlist, doc.caution.content }
         doc.caution.content = doc.title?, doc.block_elements+
         doc.caution.attlist = doc.common.block.attlist
         
         doc.orderedlist =
+            ## A list of items, where each item should show its order, typically with numbers.
             element orderedlist { doc.orderedlist.attlist, doc.orderedlist.content }
         doc.orderedlist.content = doc.listitem+
         doc.orderedlist.attlist = doc.common.block.attlist
 
         doc.itemizedlist =
+            ## A list of items, where the items do not have a particular ordering. Usually each item
+            ## is shown with a bullet of some form.
             element itemizedlist { doc.itemizedlist.attlist, doc.itemizedlist.content }
         doc.itemizedlist.content = doc.listitem+
         doc.itemizedlist.attlist = doc.common.block.attlist
     
         doc.listitem =
+            ## The contained blocks are all a single item in one of the list types.
             element listitem { doc.listitem.attlist, doc.listitem.content }
         doc.listitem.content = doc.block_elements+            
         doc.listitem.attlist = empty
             (doc.block_elements*, doc.block_section+)
         
         doc.programlisting =
+            ## The text should be displayed verbatum and in a fixed-width font.
             element programlisting { doc.programlisting.attlist, doc.programlisting.content }
         doc.programlisting.content = text
         doc.programlisting.attlist = empty
         
         doc.param_list =
+            ## A list of parameter documentation. The order of the parameters is irrelevant.
             element param-list { doc.param_list.attlist, doc.param_list.content }
         doc.param_list.content = doc.param+
         doc.param_list.attlist = empty
         
         doc.param =
+            ## The documentation for a parameter. It can be referenced by the language parameter.
             element param { doc.param.attlist, doc.param.content }
         doc.param.content = doc.block_elements+
         doc.param.attlist = pd.identifier.attribute, pd.common.name.attribute
         
         doc.throw_list =
+            ## A list of objects that the documentation states can be thrown.
+            ## Each thrown item is documented.
             element throw-list { doc.throw_list.attlist, doc.throw_list.content }
         doc.throw_list.content = doc.throw+
         doc.throw_list.attlist = empty
         
         doc.throw =
+            ## A single item that this language construct can throw.
             element throw { doc.throw.attlist, doc.throw.content }
         doc.throw.content = doc.throw_object, doc.block_elements+
         doc.throw.attlist = empty
         
         doc.throw_object =
+            ## The type of object that can be thrown.
             element throw-object { doc.throw_object.attlist, doc.throw_object.content }
         doc.throw_object.content = doc.lang_string
         doc.throw_object.attlist = empty
         
         doc.return_value =
+            ## Documentation for the return value of this function. It can be referenced by the
+            ## documented member's type.
             element return_value { doc.return_value.attlist, doc.return_value.content }
         doc.return_value.content = doc.block_elements+
         doc.return_value.attlist = pd.identifier.attribute
         
         doc.block_section = 
+            ## Represents a titled section of documentation.
             element section { doc.block_section.attlist, doc.block_section.content }
         doc.block_section.content = doc.title, doc.large_layout
         doc.block_section.attlist = doc.common.block.attlist, pd.identifier.attribute?
         
+        ## A simple string which can have references to language constructs.
         doc.lang_string = mixed { doc.lang.ref* }
     }
 }
 div
 {
     pd.codedocs.language.attribute =
+        ## The programming language that this documentation documents.
         attribute language { text }
         
     pd.codedocs.version.attribute =
+        ## The version of the ProgDoc format that this file is written against.
         attribute version { "0.9" }
     
     pd.codedocs.tool_version.attribute =
+        ## The version of the tool that generated this file.
         attribute tool-version{ text }
         
     pd.info.name.attribute =
+        ## The name of the project being documented.
         attribute name { text }
     
     pd.info.version.attribute =
+        ## The version of the project being documented.
         attribute version { text }
         
     pd.identifier.attribute =
+        ## Any location that can be referenced.
         attribute xml:id { xsd:ID }
     
-    pd.container.name.attribute =
-        attribute name { text }
-        
     pd.common.file_ref.attribute =
+        ## A reference to a file's "doc" element.
         attribute file-ref { xsd:IDREF }
         
     pd.common.doc_ref.attribute =
+        ## A reference to any kind of "doc" element.
         attribute doc-ref { xsd:IDREF }
         
     pd.common.lang_ref.attribute =
+        ## A reference to any identified language objects. Anything that satisfies
+        ## ancestor-or-self::container.
         attribute lang-ref { xsd:IDREF }
         
     pd.common.idref.attribute =
+        ## A reference to any item that can have a reference, though the use may narrow the scope.
         attribute idref { xsd:IDREF }
         
     pd.common.name.attribute =
+        ## The name of something.
         attribute name { text }
         
     pd.container.kind.attribute =
+        ## The particular kind of container that this is.
         attribute kind { "class" | "struct" | "interface" | "union" | "namespace" }
         
     pd.global.container.kind.attribute =
+        ## The kind used by the global container, which can only be "namespace"
         attribute kind { "namespace" }
         
-    pd.linkage.kind.attribute =
+    pd.inheritance.kind.attribute =
+        ## The kind of inheritance used.
         attribute kind { "public" | "protected" | "private" | "virtual" }
         
     pd.property.kind.attribute =
+        ## Properties that a container or member can have.
         attribute kind {
             "abstract" |
             "static" |
         }
         
     pd.member.kind.attribute =
+        ## The possible different kinds of members.
         attribute kind {
             "variable" |
             "property" |
         }
     
     pd.member.overrides.attribute =
+        ## References a member on a base class that this member overrides.
         attribute overrides { xsd:IDREF }
-        
-    pd.param.name.attribute =
-        attribute name { text }
 }
 
 ## Documentation attributes
     doc.common.block.attlist = doc.common.attlist
 
     doc.role.attribute =
+        ## An arbitrary string representing the role of this piece of text..
         attribute role { text }
         
     doc.style.style.attribute =
+        ## The kinds of styling that can be applied to a style element.
         attribute style
         {
             "bold" |

File Design/ToDo.txt

 * Add friend definitions to the language section.
 * Add generic references to arbitrary things, ala "link".
 * Add ToDo elements.
+* Change the member parameter and type references to use a different type from "doc-ref". This type should be reserved for references to a "doc" element.
 * Document the schema.