expressir 2.1.12 → 2.1.13

data/docs/liquid_drops.adoc

@@ -0,0 +1,1547 @@
+= Expressir Liquid drop attributes
+:toc:
+
+== Introduction
+
+== Identifier functionality
+
+Many EXPRESS model elements have an identifier and associated documentation. In Expressir, this is implemented through the `IdentifierDrop` module. When a drop class includes this module and calls `initialize_identifier`, it automatically gets the following attributes:
+
+`id`:: The identifier name of the element
+`remarks`:: Array of remarks (comments) associated with the element
+`remark_items`:: Array of structured remarks as RemarkItemDrop objects
+`source`:: The original source code representation
+
+The following drops include Identifier functionality:
+
+* Schema drops
+* Type drops
+* Entity drops
+* Function drops
+* Procedure drops
+* Attribute drops
+* Constant drops
+* Variable drops
+* Parameter drops
+* Rule drops
+* Where rule drops
+* Unique rule drops
+* Subtype constraint drops
+* Generic drops
+* Generic entity drops
+* Enumeration item drops
+* Aggregate drops
+* Query expression drops
+* Alias statement drops
+
+Each of these drops will have the above attributes in addition to their specific attributes.
+
+Example using identifier attributes:
+
+[source,liquid]
+----
+Name: {{ item.id }}
+
+{% if item.remarks.size > 0 %}
+Documentation:
+{% for remark in item.remarks %}
+* {{ remark }}
+{% endfor %}
+{% endif %}
+
+{% if item.remark_items.size > 0 %}
+Structured Documentation:
+{% for ritem in item.remark_items %}
+* {{ ritem.id }}: {{ ritem.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+
+Source:
+{{ item.source }}
+----
+
+=== Identifier implementation details
+
+The identifier functionality is implemented in the `IdentifierDrop` module located in `lib/expressir/liquid/identifier_drop.rb`. Classes include this module and call `initialize_identifier` in their initializer to get the standard identifier attributes.
+
+Example implementation pattern:
+
+[source,ruby]
+----
+class MyDrop < ModelElementDrop
+  include IdentifierDrop
+  
+  def initialize(model)
+    super
+    initialize_identifier
+  end
+end
+----
+
+=== Error handling with identifier attributes
+
+When working with identifier attributes, consider these error handling patterns:
+
+[source,liquid]
+----
+  {% if item %}
+    {% if item.id %}{{ item.id }}{% else %}[Unnamed]{% endif %}
+  {% else %}
+    [Invalid Item]
+  {% endif %}
+
+  {% if item and item.remarks %}
+    {% for remark in item.remarks %}
+      - {{ remark }}
+    {% endfor %}
+  {% endif %}
+
+  {% if item and item.source %}{{ item.source }}{% else %}[No Source Available]{% endif %}
+----
+
+== Drop categories and attributes
+
+=== Base drops
+
+==== ModelElementDrop
+
+Base class for all drops.
+
+Attributes:
+
+`_class`:: Returns the class name of the model
+`file`:: Returns the file path if the model responds to it
+`source`:: Returns the source if the model responds to it
+
+==== DeclarationDrop
+
+Inherits from ModelElementDrop.
+
+=== Repository and schema drops
+
+==== RepositoryDrop
+
+Represents the root container for schemas.
+
+Attributes:
+
+`schemas`:: Array of SchemaDrop objects
+
+==== SchemaDrop
+
+Represents an EXPRESS SCHEMA declaration. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Schema name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`file`:: Schema file path
+`file_basename`:: Base name of schema file
+`selected`:: Boolean indicating if schema is selected
+`relative_path_prefix`:: Relative path prefix for document
+`version`:: SchemaVersionDrop object
+`interfaces`:: Array of InterfaceDrop objects
+`constants`:: Array of ConstantDrop objects
+`types`:: Array of TypeDrop objects
+`entities`:: Array of EntityDrop objects
+`subtype_constraints`:: Array of SubtypeConstraintDrop objects
+`functions`:: Array of FunctionDrop objects
+`rules`:: Array of RuleDrop objects
+`procedures`:: Array of ProcedureDrop objects
+`formatted`:: Formatted string representation
+
+==== SchemaVersionDrop
+
+Represents schema version information.
+
+Attributes:
+
+`value`:: Version string value
+`items`:: Array of SchemaVersionItemDrop objects
+
+==== SchemaVersionItemDrop
+
+Represents individual version items.
+
+Attributes:
+
+`name`:: Item name
+`value`:: Item value
+
+=== Interface drops
+
+==== InterfaceDrop
+
+Represents schema interfaces (USE FROM and REFERENCE FROM).
+
+Attributes:
+
+`kind`:: Interface kind ('use' or 'reference')
+`schema`:: Reference to schema being interfaced
+`items`:: Array of InterfaceItemDrop objects
+
+==== InterfaceItemDrop
+
+Represents items in an interface.
+
+Attributes:
+
+`ref`:: Reference to the interfaced item
+`id`:: Identifier name
+
+==== InterfacedItemDrop
+
+Represents an item that has been interfaced.
+
+Attributes:
+
+`id`:: Identifier name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`base_item`:: Reference to the original item
+
+=== Declaration drops
+
+==== AttributeDrop
+
+Represents an entity attribute. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Attribute name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`kind`:: Kind of attribute (explicit, derived, inverse)
+`supertype_attribute`:: Reference to attribute in supertype if inherited
+`optional`:: Boolean indicating if attribute is optional
+`type`:: DataTypeDrop representing attribute type
+`expression`:: ExpressionDrop for derived attributes
+
+==== ConstantDrop
+
+Represents schema-level constants. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Constant name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`type`:: DataTypeDrop representing constant type
+`expression`:: ExpressionDrop representing constant value
+
+==== EntityDrop
+
+Represents an EXPRESS entity. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Entity name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`abstract`:: Boolean indicating if entity is abstract
+`supertype_expression`:: SupertypeExpressionDrop
+`subtype_of`:: Array of references to supertypes
+`attributes`:: Array of AttributeDrop objects
+`unique_rules`:: Array of UniqueRuleDrop objects
+`where_rules`:: Array of WhereRuleDrop objects
+`informal_propositions`:: Array of RemarkItemDrop objects
+
+==== FunctionDrop
+
+Represents an EXPRESS function. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Function name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`parameters`:: Array of ParameterDrop objects
+`return_type`:: DataTypeDrop representing return type
+`types`:: Array of TypeDrop objects
+`entities`:: Array of EntityDrop objects
+`subtype_constraints`:: Array of SubtypeConstraintDrop objects
+`functions`:: Array of FunctionDrop objects
+`procedures`:: Array of ProcedureDrop objects
+`constants`:: Array of ConstantDrop objects
+`variables`:: Array of VariableDrop objects
+`statements`:: Array of StatementDrop objects
+
+==== ParameterDrop
+
+Represents function/procedure parameters. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Parameter name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`var`:: Boolean indicating if parameter is VAR (variable)
+`type`:: DataTypeDrop representing parameter type
+
+==== ProcedureDrop
+
+Represents an EXPRESS procedure. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Procedure name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`parameters`:: Array of ParameterDrop objects
+`types`:: Array of TypeDrop objects
+`entities`:: Array of EntityDrop objects
+`subtype_constraints`:: Array of SubtypeConstraintDrop objects
+`functions`:: Array of FunctionDrop objects
+`procedures`:: Array of ProcedureDrop objects
+`constants`:: Array of ConstantDrop objects
+`variables`:: Array of VariableDrop objects
+`statements`:: Array of StatementDrop objects
+
+==== RemarkItemDrop
+
+Represents structured remarks.
+
+Attributes:
+
+`id`:: Remark identifier
+`remarks`:: Array of remark content strings
+
+==== RuleDrop
+
+Represents EXPRESS global rules. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Rule name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`applies_to`:: Array of references to entities rule applies to
+`types`:: Array of TypeDrop objects
+`entities`:: Array of EntityDrop objects
+`subtype_constraints`:: Array of SubtypeConstraintDrop objects
+`functions`:: Array of FunctionDrop objects
+`procedures`:: Array of ProcedureDrop objects
+`constants`:: Array of ConstantDrop objects
+`variables`:: Array of VariableDrop objects
+`statements`:: Array of StatementDrop objects
+`where_rules`:: Array of WhereRuleDrop objects
+`informal_propositions`:: Array of RemarkItemDrop objects
+
+==== TypeDrop
+
+Represents EXPRESS type definitions. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Type name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`underlying_type`:: DataTypeDrop representing base type
+`where_rules`:: Array of WhereRuleDrop objects
+`informal_propositions`:: Array of RemarkItemDrop objects
+
+==== UniqueRuleDrop
+
+Represents UNIQUE rules in entities. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Rule name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`attributes`:: Array of references to attributes
+
+==== VariableDrop
+
+Represents local variables. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Variable name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`type`:: DataTypeDrop representing variable type
+`expression`:: ExpressionDrop representing initial value
+
+==== WhereRuleDrop
+
+Represents WHERE rules. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Rule name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`expression`:: ExpressionDrop representing rule condition
+
+=== Data type drops
+
+==== AggregateDrop
+
+Base class for aggregate types. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Type name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`base_type`:: DataTypeDrop representing element type
+
+==== ArrayDrop
+
+Represents EXPRESS ARRAY type.
+
+Attributes:
+
+`bound1`:: Lower bound expression
+`bound2`:: Upper bound expression
+`optional`:: Boolean indicating if array is optional
+`unique`:: Boolean indicating if elements must be unique
+`base_type`:: DataTypeDrop representing element type
+
+==== BagDrop
+
+Represents EXPRESS BAG type.
+
+Attributes:
+
+`bound1`:: Lower bound expression
+`bound2`:: Upper bound expression
+`base_type`:: DataTypeDrop representing element type
+
+==== BinaryDrop
+
+Represents EXPRESS BINARY type.
+
+Attributes:
+
+`width`:: Width specification expression
+`fixed`:: Boolean indicating if width is fixed
+
+==== BooleanDrop
+
+Represents EXPRESS BOOLEAN type.
+
+==== EnumerationDrop
+
+Represents EXPRESS ENUMERATION type.
+
+Attributes:
+
+`extensible`:: Boolean indicating if enumeration is extensible
+`based_on`:: Reference to base enumeration
+`items`:: Array of EnumerationItemDrop objects
+
+==== EnumerationItemDrop
+
+Represents items in an enumeration. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Item name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+
+==== GenericDrop
+
+Represents EXPRESS GENERIC type. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Type name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+
+==== GenericEntityDrop
+
+Represents EXPRESS GENERIC_ENTITY type. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Type name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+
+==== IntegerDrop
+
+Represents EXPRESS INTEGER type.
+
+==== ListDrop
+
+Represents EXPRESS LIST type.
+
+Attributes:
+
+`bound1`:: Lower bound expression
+`bound2`:: Upper bound expression
+`unique`:: Boolean indicating if elements must be unique
+`base_type`:: DataTypeDrop representing element type
+
+==== LogicalDrop
+
+Represents EXPRESS LOGICAL type.
+
+==== RealDrop
+
+Represents EXPRESS REAL type.
+
+Attributes:
+
+`precision`:: Precision specification expression
+
+==== SelectDrop
+
+Represents EXPRESS SELECT type.
+
+Attributes:
+
+`extensible`:: Boolean indicating if select is extensible
+`generic_entity`:: Boolean indicating if select is generic entity
+`based_on`:: Reference to base select
+`items`:: Array of references to select items
+
+==== SetDrop
+
+Represents EXPRESS SET type.
+
+Attributes:
+
+`bound1`:: Lower bound expression
+`bound2`:: Upper bound expression
+`base_type`:: DataTypeDrop representing element type
+
+==== StringDrop
+
+Represents EXPRESS STRING type.
+
+Attributes:
+
+`width`:: Width specification expression
+`fixed`:: Boolean indicating if width is fixed
+
+=== Expression drops
+
+==== AggregateInitializerDrop
+
+Represents aggregate initialization expressions.
+
+Attributes:
+
+`items`:: Array of AggregateInitializerItemDrop objects
+
+==== AggregateInitializerItemDrop
+
+Represents items in an aggregate initializer.
+
+Attributes:
+
+`expression`:: ExpressionDrop representing item value
+`repetition`:: ExpressionDrop representing repetition count
+
+==== BinaryExpressionDrop
+
+Represents binary operations.
+
+Attributes:
+
+`operator`:: Operator symbol
+`operand1`:: ExpressionDrop for first operand
+`operand2`:: ExpressionDrop for second operand
+
+==== EntityConstructorDrop
+
+Represents entity constructor expressions.
+
+Attributes:
+
+`entity`:: Reference to entity being constructed
+`items`:: Array of entity constructor items
+
+==== FunctionCallDrop
+
+Represents function call expressions.
+
+Attributes:
+
+`function`:: Reference to called function
+`parameters`:: Array of parameter expressions
+
+==== IntervalDrop
+
+Represents interval expressions.
+
+Attributes:
+
+`operator`:: Interval operator
+`operand1`:: Lower bound expression
+`operand2`:: Upper bound expression
+
+==== QueryExpressionDrop
+
+Represents QUERY expressions.
+
+Attributes:
+
+`id`:: Query variable name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`aggregate_source`:: Expression providing source collection
+`expression`:: Query filter expression
+
+==== UnaryExpressionDrop
+
+Represents unary operations.
+
+Attributes:
+
+`operator`:: Operator symbol
+`operand`:: ExpressionDrop for operand
+
+=== Literal drops
+
+==== BinaryDrop
+
+Represents binary literals.
+
+Attributes:
+
+`value`:: Binary value
+
+==== IntegerDrop
+
+Represents integer literals.
+
+Attributes:
+
+`value`:: Integer value
+
+==== LogicalDrop
+
+Represents logical literals.
+
+Attributes:
+
+`value`:: Logical value (TRUE, FALSE, UNKNOWN)
+
+==== RealDrop
+
+Represents real number literals.
+
+Attributes:
+
+`value`:: Real number value
+
+==== StringDrop
+
+Represents string literals.
+
+Attributes:
+
+`value`:: String value
+`encoded`:: Boolean indicating if string is encoded
+
+=== Reference drops
+
+==== AttributeReferenceDrop
+
+Represents references to attributes.
+
+Attributes:
+
+`base`:: Reference to base entity/type
+`attribute`:: Reference to attribute
+
+==== GroupReferenceDrop
+
+Represents references to groups.
+
+Attributes:
+
+`base`:: Reference to base entity/type
+`group`:: Reference to group
+
+==== IndexReferenceDrop
+
+Represents array/list index references.
+
+Attributes:
+
+`base`:: Reference to aggregate
+`index1`:: First index expression
+`index2`:: Second index expression (for ranges)
+
+==== SimpleReferenceDrop
+
+Represents simple named references.
+
+Attributes:
+
+`id`:: Referenced name
+
+=== Statement drops
+
+==== AliasDrop
+
+Represents ALIAS statements. Includes identifier functionality.
+
+Attributes:
+
+`id`:: Alias name
+`remarks`:: Array of remarks
+`remark_items`:: Array of RemarkItemDrop objects
+`source`:: Source code representation
+`expression`:: Referenced expression
+`statements`:: Array of statements in alias block
+
+==== AssignmentDrop
+
+Represents assignment statements.
+
+Attributes:
+
+`expression1`:: Target expression
+`expression2`:: Value expression
+
+==== CaseActionDrop
+
+Represents CASE action clauses.
+
+Attributes:
+
+`labels`:: Array of case label expressions
+`statement`:: Statement to execute
+
+==== CaseDrop
+
+Represents CASE statements.
+
+Attributes:
+
+`expression`:: Selector expression
+`actions`:: Array of CaseActionDrop objects
+`otherwise`:: Otherwise statement
+
+==== CompoundDrop
+
+Represents compound statements.
+
+Attributes:
+
+`statements`:: Array of statements
+
+==== EscapeDrop
+
+Represents ESCAPE statements.
+
+==== IfDrop
+
+Represents IF statements.
+
+Attributes:
+
+`expression`:: Condition expression
+`statements`:: Array of statements in then branch
+`else_statements`:: Array of statements in else branch
+
+==== NullDrop
+
+Represents NULL statements.
+
+==== ProcedureCallDrop
+
+Represents procedure call statements.
+
+Attributes:
+
+`procedure`:: Reference to called procedure
+`parameters`:: Array of parameter expressions
+
+==== RepeatDrop
+
+Represents REPEAT statements.
+
+Attributes:
+
+`expression`:: Loop condition expression
+`statements`:: Array of statements in loop body
+
+==== ReturnDrop
+
+Represents RETURN statements.
+
+Attributes:
+
+`expression`:: Return value expression
+
+==== SkipDrop
+
+Represents SKIP statements.
+
+=== Constant drop
+
+Represents EXPRESS CONSTANT declarations at the schema level. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (constant name)
+`remarks`::: Array of remarks associated with the constant
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+
+* Constant-specific attributes:
+
+`type`::: DataTypeDrop representing the constant's type
+`expression`::: ExpressionDrop representing the constant's value
+
+Example EXPRESS:
+
+[source,express]
+----
+CONSTANT
+  (* Mathematical constant *)
+  PI : REAL := 3.14159;
+  (* System limits *)
+  MAX_ITEMS : INTEGER := 1000;
+  (* Default text *)
+  DEFAULT_NAME : STRING := 'Untitled';
+END_CONSTANT;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+Constants:
+{% for const in schema.constants %}
+{{ const.id }}:
+  Type: {{ const.type._class }}
+  Value: {{ const.expression.value }}
+  
+  Documentation:
+  {% for remark in const.remarks %}
+  - {{ remark }}
+  {% endfor %}
+  
+  Source:
+  {{ const.source }}
+  
+  {% if const.remark_items %}
+  Structured Documentation:
+  {% for item in const.remark_items %}
+  - {{ item.id }}: {{ item.remarks | join: " " }}
+  {% endfor %}
+  {% endif %}
+{% endfor %}
+----
+
+=== Query expression drop
+
+Represents an EXPRESS QUERY expression. Includes identifier functionality through `IdentifierDrop` since queries can have variable declarations.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (query variable name)
+`remarks`::: Array of remarks associated with the query
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+
+* Query-specific attributes:
+
+`aggregate_source`::: Expression providing the source collection
+`expression`::: Query filter expression
+
+Example EXPRESS:
+
+[source,express]
+----
+RULE find_expensive_items FOR (catalog);
+WHERE
+  (* Find items above price threshold *)
+  has_expensive : QUERY (
+    (* Iterator for catalog items *)
+    item <* catalog.items |
+    (* Check price threshold *)
+    item.price > 1000.0
+  ) > 0;
+END_RULE;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+Query Variable: {{ query.id }}
+
+Documentation:
+{% for remark in query.remarks %}
+- {{ remark }}
+{% endfor %}
+
+Source:
+{{ query.source }}
+
+{% if query.remark_items %}
+Structured Documentation:
+{% for item in query.remark_items %}
+- {{ item.id }}: {{ item.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+
+Source Collection: {{ query.aggregate_source }}
+Filter: {{ query.expression }}
+----
+
+=== Generic drop
+
+Represents an EXPRESS GENERIC type. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (generic type name)
+`remarks`::: Array of remarks associated with the generic type
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+
+Example EXPRESS:
+
+[source,express]
+----
+TYPE list_type = LIST OF GENERIC;
+  (* Generic list type *)
+  (* Author: Jane Smith *)
+END_TYPE;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+Generic Type: {{ type.id }}
+
+Documentation:
+{% for remark in type.remarks %}
+- {{ remark }}
+{% endfor %}
+
+Source:
+{{ type.source }}
+
+{% if type.remark_items %}
+Structured Documentation:
+{% for item in type.remark_items %}
+- {{ item.id }}: {{ item.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+----
+
+=== Generic entity drop
+
+Represents an EXPRESS GENERIC_ENTITY type. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (generic entity name)
+`remarks`::: Array of remarks associated with the generic entity
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+
+Example EXPRESS:
+
+[source,express]
+----
+TYPE container = SET OF GENERIC_ENTITY;
+  (* Generic entity container *)
+  (* Supports any entity type *)
+END_TYPE;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+Generic Entity: {{ type.id }}
+
+Documentation:
+{% for remark in type.remarks %}
+- {{ remark }}
+{% endfor %}
+
+Source:
+{{ type.source }}
+
+{% if type.remark_items %}
+Structured Documentation:
+{% for item in type.remark_items %}
+- {{ item.id }}: {{ item.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+{% endfor %}
+----
+
+=== Enumeration item drop
+
+Represents items in an EXPRESS ENUMERATION type. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (enumeration value name)
+`remarks`::: Array of remarks associated with the enumeration item
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+
+Example EXPRESS:
+
+[source,express]
+----
+TYPE color = ENUMERATION OF
+  (* Basic colors *)
+  red,    (* Primary color *)
+  green,  (* Primary color *)
+  blue,   (* Primary color *)
+  (* Extended colors *)
+  yellow, (* Secondary color *)
+  purple  (* Secondary color *)
+);
+END_TYPE;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+{% for item in type.underlying_type.items %}
+Value: {{ item.id }}
+
+Documentation:
+{% for remark in item.remarks %}
+- {{ remark }}
+{% endfor %}
+
+Source:
+{{ item.source }}
+
+{% if item.remark_items %}
+Structured Documentation:
+{% for ritem in item.remark_items %}
+- {{ ritem.id }}: {{ ritem.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+{% endfor %}
+----
+
+=== Aggregate drop
+
+Represents an EXPRESS aggregate type definition. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (aggregate type name)
+`remarks`::: Array of remarks associated with the aggregate type
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+* Aggregate-specific attributes:
+
+`base_type`::: DataTypeDrop representing the element type
+
+Example EXPRESS:
+
+[source,express]
+----
+TYPE point_list = LIST OF point;
+  (* List of geometric points *)
+  (* Used for polylines *)
+END_TYPE;
+
+TYPE color_set = SET OF color;
+  (* Set of unique colors *)
+  (* For color palettes *)
+END_TYPE;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+Aggregate Type: {{ type.id }}
+Base Type: {{ type.base_type._class }}
+
+Documentation:
+{% for remark in type.remarks %}
+- {{ remark }}
+{% endfor %}
+
+Source:
+{{ type.source }}
+
+{% if type.remark_items %}
+Structured Documentation:
+{% for item in type.remark_items %}
+- {{ item.id }}: {{ item.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+----
+
+=== Alias statement drop
+
+Represents an EXPRESS ALIAS statement. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (alias name)
+`remarks`::: Array of remarks associated with the alias
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+* Alias-specific attributes:
+
+`expression`::: The referenced expression
+`statements`::: Array of statements in the ALIAS block
+
+Example EXPRESS:
+
+[source,express]
+----
+FUNCTION process_point(p : point) : REAL;
+  (* Create alias for readability *)
+  ALIAS coord := p.coordinates;
+    (* Compute using aliased value *)
+    result := coord.x * coord.y;
+  END_ALIAS;
+  RETURN result;
+END_FUNCTION;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+{% for statement in function.statements %}
+  {% if statement._class contains "Alias" %}
+  Alias: {{ statement.id }}
+  
+  Documentation:
+  {% for remark in statement.remarks %}
+  - {{ remark }}
+  {% endfor %}
+  
+  Source:
+  {{ statement.source }}
+  
+  {% if statement.remark_items %}
+  Structured Documentation:
+  {% for item in statement.remark_items %}
+  - {{ item.id }}: {{ item.remarks | join: " " }}
+  {% endfor %}
+  {% endif %}
+  
+  Expression: {{ statement.expression }}
+  {% endif %}
+{% endfor %}
+----
+
+=== Variable drop
+
+Represents EXPRESS variable declarations in functions and procedures. Includes identifier functionality through `IdentifierDrop`.
+
+Attributes:
+
+* [Added by IdentifierDrop]:
+
+`id`::: Identifier name (variable name)
+`remarks`::: Array of remarks associated with the variable
+`remark_items`::: Array of RemarkItemDrop objects containing structured remarks
+`source`::: Source code representation
+* Variable-specific attributes:
+
+`type`::: DataTypeDrop representing the variable's type
+`expression`::: ExpressionDrop representing the optional initial value
+
+Example EXPRESS:
+
+[source,express]
+----
+FUNCTION calculate_area(width, height: REAL) : REAL;
+  LOCAL
+    (* Temporary result storage *)
+    result : REAL := 0.0;
+    (* Status flag *)
+    valid : BOOLEAN := TRUE;
+  END_LOCAL;
+  
+  result := width * height;
+  RETURN result;
+END_FUNCTION;
+----
+
+Example usage showing identifier functionality:
+
+[source,liquid]
+----
+Local Variables:
+{% for var in function.variables %}
+{{ var.id }}:
+  Type: {{ var.type._class }}
+  {% if var.expression %}
+  Initial Value: {{ var.expression }}
+  {% endif %}
+  
+  Documentation:
+  {% for remark in var.remarks %}
+  - {{ remark }}
+  {% endfor %}
+  
+  Source:
+  {{ var.source }}
+  
+  {% if var.remark_items %}
+  Structured Documentation:
+  {% for item in var.remark_items %}
+  - {{ item.id }}: {{ item.remarks | join: " " }}
+  {% endfor %}
+  {% endif %}
+{% endfor %}
+----
+
+=== Working with remark items
+
+Remark items provide a structured way to handle documentation in EXPRESS schemas. Unlike plain remarks, remark items have both an identifier and content, making them suitable for metadata and categorized documentation.
+
+Example EXPRESS with structured remarks:
+
+[source,express]
+----
+SCHEMA building_schema;
+  (* @Author: John Smith *)
+  (* @Version: 1.0 *)
+  (* @Date: 2024-01-15 *)
+  (* @Description: Building information model *)
+  
+  TYPE length_measure = REAL;
+    (* @Unit: meters *)
+    (* @Precision: 0.001 *)
+  END_TYPE;
+  
+  ENTITY wall;
+    (* @Property: structural *)
+    (* @Material: concrete *)
+    height : length_measure;
+    width : length_measure;
+  END_ENTITY;
+END_SCHEMA;
+----
+
+Example template for handling remark items:
+
+[source,liquid]
+----
+{%- comment %}Group remarks by category{% endcomment %}
+{% assign metadata = [] %}
+{% assign technical = [] %}
+{% assign other = [] %}
+
+{% for ritem in item.remark_items %}
+  {% case ritem.id %}
+  {% when 'Author', 'Version', 'Date' %}
+    {% assign metadata = metadata | push: ritem %}
+  {% when 'Unit', 'Precision', 'Property', 'Material' %}
+    {% assign technical = technical | push: ritem %}
+  {% else %}
+    {% assign other = other | push: ritem %}
+  {% endcase %}
+{% endfor %}
+
+{% if metadata.size > 0 %}
+Metadata:
+{% for ritem in metadata %}
+- {{ ritem.id }}: {{ ritem.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+
+{% if technical.size > 0 %}
+Technical Details:
+{% for ritem in technical %}
+- {{ ritem.id }}: {{ ritem.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+
+{% if other.size > 0 %}
+Additional Information:
+{% for ritem in other %}
+- {{ ritem.id }}: {{ ritem.remarks | join: " " }}
+{% endfor %}
+{% endif %}
+----
+
+Using the template:
+
+[source,liquid]
+----
+Schema Documentation:
+{{ process_remark_items schema }}
+
+Types:
+{% for type in schema.types %}
+{{ type.id }}:
+{{ process_remark_items type }}
+{% endfor %}
+
+Entities:
+{% for entity in schema.entities %}
+{{ entity.id }}:
+{{ process_remark_items entity }}
+
+Attributes:
+{% for attr in entity.attributes %}
+{{ attr.id }}:
+{{ process_remark_items attr }}
+{% endfor %}
+{% endfor %}
+----
+
+Example output:
+
+[source,text]
+----
+Schema Documentation:
+Metadata:
+- Author: John Smith
+- Version: 1.0
+- Date: 2024-01-15
+
+Additional Information:
+- Description: Building information model
+
+Types:
+length_measure:
+Technical Details:
+- Unit: meters
+- Precision: 0.001
+
+Entities:
+wall:
+Technical Details:
+- Property: structural
+- Material: concrete
+----
+
+This structured approach makes it easier to:
+- Generate consistent documentation
+- Filter and categorize documentation elements
+- Support multiple documentation formats
+- Maintain metadata separate from general documentation
+- Generate different views of the same documentation
+
+=== Common remark item patterns
+
+Here are some common patterns for working with remark items in templates:
+
+==== Filtering by category
+
+[source,liquid]
+----
+{% assign filtered = [] %}
+{% for ritem in item.remark_items %}
+  {% if ritem.id == category %}
+    {% assign filtered = filtered | push: ritem %}
+  {% endif %}
+{% endfor %}
+{{ filtered | map: "remarks" | join: " " }}
+
+{%- comment %}Usage examples:{% endcomment %}
+Author: {{ get_remarks_by_category schema "Author" }}
+Version: {{ get_remarks_by_category schema "Version" }}
+----
+
+==== Creating documentation tables
+
+[source,liquid]
+----
+|===
+|Category |Value
+
+{% for ritem in item.remark_items %}
+|{{ ritem.id }}
+|{{ ritem.remarks | join: " " }}
+{% endfor %}
+|===
+----
+
+==== Inheritance-aware documentation
+
+[source,liquid]
+----
+{%- comment %}Get direct remarks{% endcomment %}
+{% assign all_remarks = entity.remark_items %}
+
+{%- comment %}Get inherited remarks{% endcomment %}
+{% for super in entity.subtype_of %}
+  {% for ritem in super.remark_items %}
+    {% assign all_remarks = all_remarks | push: ritem %}
+  {% endfor %}
+{% endfor %}
+
+{%- comment %}Remove duplicates by ID{% endcomment %}
+{% assign unique_remarks = [] %}
+{% for ritem in all_remarks %}
+  {% unless unique_remarks | map: "id" | contains: ritem.id %}
+    {% assign unique_remarks = unique_remarks | push: ritem %}
+  {% endunless %}
+{% endfor %}
+
+{% for ritem in unique_remarks %}
+- {{ ritem.id }}: {{ ritem.remarks | join: " " }}
+{% endfor %}
+----
+
+These patterns help maintain consistency and structure when working with documentation in EXPRESS schemas.
+
+== Drop inheritance hierarchy
+
+Here's how the drops are organized hierarchically:
+
+* ModelElementDrop
+** DeclarationDrop
+*** EntityDrop
+*** TypeDrop
+*** FunctionDrop
+*** ProcedureDrop
+*** RuleDrop
+*** WhereRuleDrop
+*** UniqueRuleDrop
+*** ConstantDrop
+*** VariableDrop
+*** ParameterDrop
+*** AttributeDrop
+** ExpressionDrop
+*** BinaryExpressionDrop
+*** UnaryExpressionDrop
+*** QueryExpressionDrop
+*** FunctionCallDrop
+*** EntityConstructorDrop
+*** AggregateInitializerDrop
+*** IntervalDrop
+** DataTypeDrop
+*** AggregateDrop
+**** ArrayDrop
+**** BagDrop
+**** ListDrop
+**** SetDrop
+*** BinaryDrop
+*** BooleanDrop
+*** EnumerationDrop
+*** GenericDrop
+*** GenericEntityDrop
+*** IntegerDrop
+*** LogicalDrop
+*** RealDrop
+*** SelectDrop
+*** StringDrop
+** ReferenceDrop
+*** SimpleReferenceDrop
+*** AttributeReferenceDrop
+*** GroupReferenceDrop
+*** IndexReferenceDrop
+** StatementDrop
+*** AliasDrop
+*** AssignmentDrop
+*** CaseDrop
+*** CompoundDrop
+*** EscapeDrop
+*** IfDrop
+*** NullDrop
+*** ProcedureCallDrop
+*** RepeatDrop
+*** ReturnDrop
+*** SkipDrop
+** LiteralDrop
+*** BinaryDrop
+*** IntegerDrop
+*** LogicalDrop
+*** RealDrop
+*** StringDrop
+
+=== Common inheritance patterns
+
+When working with drops that share a common base class, you can use patterns like:
+
+[source,liquid]
+----
+{% for item in items %}
+  {% case item._class %}
+  {% when 'EntityDrop' %}
+    // Process entity
+  {% when 'TypeDrop' %}
+    // Process type
+  {% when 'FunctionDrop' %}
+    // Process function
+  {% else %}
+    // Handle other declarations
+  {% endcase %}
+{% endfor %}
+
+{% for expr in exprs %}
+  {% case expr._class %}
+  {% when 'BinaryExpressionDrop' %}
+    {{ expr.operand1 }} {{ expr.operator }} {{ expr.operand2 }}
+  {% when 'UnaryExpressionDrop' %}
+    {{ expr.operator }}{{ expr.operand }}
+  {% when 'QueryExpressionDrop' %}
+    QUERY({{ expr.id }} <* {{ expr.aggregate_source }} | {{ expr.expression }})
+  {% else %}
+    {{ expr }}
+  {% endcase %}
+{% endfor %}
+----
+
+=== Common base class attributes
+
+When working with drops, remember these common attributes available through inheritance:
+
+1. From ModelElementDrop:
+
+`_class`:: Type of drop
+`file`:: Source file (if applicable)
+`source`:: Original source code
+
+2. From DeclarationDrop:
+
+* All ModelElementDrop attributes
+* Additional structure for named declarations
+
+3. When IdentifierDrop is included:
+
+`id`:: Identifier name
+`remarks`:: Documentation comments
+`remark_items`:: Structured documentation
+`source`:: Source representation