Skip to content

Commit c31236a

Browse files
dmealingclaude
dmealing
and
claude
committed
DOCUMENTATION: Complete Provider-Based Registration Documentation Update
- Updated CLAUDE.md to eliminate all @MetaDataType annotation references - Replaced deprecated annotation examples with current provider-based patterns - Added comprehensive HTML documentation generator with professional styling - Fixed code examples to show MetaDataTypeProvider service discovery patterns - Updated plugin development examples to use provider-based registration - Corrected terminology from static initializers to provider-based approach - Added test suite for HTML documentation generation with target/html output 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent cd2cfac commit c31236a

27 files changed

Lines changed: 3445 additions & 197 deletions

‎.claude/CLAUDE.md‎

Lines changed: 267 additions & 182 deletions
Large diffs are not rendered by default.

‎codegen-base/pom.xml‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,13 @@
2828
<version>${project.version}</version>
2929
</dependency>
3030

31+
<!-- JSON Dependencies for Code Generation -->
32+
<dependency>
33+
<groupId>com.google.code.gson</groupId>
34+
<artifactId>gson</artifactId>
35+
<version>2.13.1</version>
36+
</dependency>
37+
3138
<!-- Test Dependencies -->
3239
<dependency>
3340
<groupId>com.draagon</groupId>
@@ -36,7 +43,15 @@
3643
<type>test-jar</type>
3744
<scope>test</scope>
3845
</dependency>
39-
46+
47+
<!-- Schema Validation Dependencies for Testing -->
48+
<dependency>
49+
<groupId>com.networknt</groupId>
50+
<artifactId>json-schema-validator</artifactId>
51+
<version>1.5.1</version>
52+
<scope>test</scope>
53+
</dependency>
54+
4055
<!-- Inherited from parent POM: SLF4J, JUnit, Logback -->
4156
</dependencies>
4257

‎codegen-base/src/main/java/com/draagon/meta/generator/direct/metadata/file/json/MetaDataFileSchemaWriter.java‎

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -232,9 +232,20 @@ private JsonObject createMetaDataChildSchema() {
232232

233233
for (String primaryType : primaryTypes) {
234234
JsonObject wrapper = new JsonObject();
235-
JsonObject property = new JsonObject();
236-
property.add("$ref", new JsonPrimitive("#/$defs/" + capitalizeFirstLetter(primaryType)));
237-
wrapper.add(primaryType, property);
235+
wrapper.addProperty("type", "object");
236+
237+
// Create properties object
238+
JsonObject properties = new JsonObject();
239+
JsonObject typeRef = new JsonObject();
240+
typeRef.add("$ref", new JsonPrimitive("#/$defs/" + capitalizeFirstLetter(primaryType)));
241+
properties.add(primaryType, typeRef);
242+
wrapper.add("properties", properties);
243+
244+
// Add required array
245+
JsonArray required = new JsonArray();
246+
required.add(primaryType);
247+
wrapper.add("required", required);
248+
238249
oneOf.add(wrapper);
239250
}
240251

@@ -328,8 +339,9 @@ private JsonObject createNameConstraintsSchema() {
328339
nameSchema.addProperty("type", "string");
329340
nameSchema.addProperty("description", "Name following MetaData naming constraints");
330341

331-
// Use pattern from MetaDataConstants
332-
nameSchema.addProperty("pattern", VALID_NAME_PATTERN);
342+
// Use pattern from MetaDataConstants, converted for JSON Schema (remove anchors)
343+
String jsonSchemaPattern = VALID_NAME_PATTERN.replaceAll("^\\^|\\$$", ""); // Remove ^ and $
344+
nameSchema.addProperty("pattern", jsonSchemaPattern);
333345
nameSchema.addProperty("minLength", 1);
334346
nameSchema.addProperty("maxLength", 64);
335347

‎codegen-base/src/main/java/com/draagon/meta/generator/direct/metadata/file/xsd/MetaDataFileXSDWriter.java‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -340,9 +340,10 @@ private Element createNameConstraintType(Document doc) {
340340
restriction.setAttribute("base", "xs:string");
341341
simpleType.appendChild(restriction);
342342

343-
// Use pattern from MetaDataConstants
343+
// Use pattern from MetaDataConstants, converted for XML Schema (remove anchors)
344344
Element patternFacet = doc.createElement("xs:pattern");
345-
patternFacet.setAttribute("value", VALID_NAME_PATTERN);
345+
String xmlSchemaPattern = VALID_NAME_PATTERN.replaceAll("^\\^|\\$$", ""); // Remove ^ and $
346+
patternFacet.setAttribute("value", xmlSchemaPattern);
346347
restriction.appendChild(patternFacet);
347348

348349
// Add length facets

‎codegen-base/src/main/java/com/draagon/meta/generator/direct/metadata/html/MetaDataHtmlDocumentationGenerator.java‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
package com.draagon.meta.generator.direct.metadata.html;
2+
3+
import com.draagon.meta.generator.GeneratorIOException;
4+
import com.draagon.meta.loader.MetaDataLoader;
5+
import org.slf4j.Logger;
6+
import org.slf4j.LoggerFactory;
7+
8+
import java.io.OutputStream;
9+
10+
/**
11+
* Professional HTML documentation generator for MetaObjects framework.
12+
*
13+
* Generates comprehensive, human-readable HTML documentation with:
14+
* - Modern responsive design with sidebar navigation
15+
* - Type hierarchy visualization with inheritance relationships
16+
* - Detailed type definitions with examples and usage patterns
17+
* - Plugin development guides and extension patterns
18+
* - Search functionality and cross-references
19+
* - Professional styling optimized for developer experience
20+
*
21+
* This generator operates directly from the TypeDefinition registry without requiring
22+
* any metadata files, making it suitable for JAR-based generation in Maven builds.
23+
*
24+
* Usage in Maven plugin:
25+
* {@code
26+
* <generator>
27+
* <classname>com.draagon.meta.generator.direct.metadata.html.MetaDataHtmlDocumentationGenerator</classname>
28+
* <args>
29+
* <outputDir>${project.build.directory}/generated-docs</outputDir>
30+
* <outputFilename>metaobjects-documentation.html</outputFilename>
31+
* <title>MetaObjects Framework Documentation</title>
32+
* <version>6.2.0</version>
33+
* <includeInheritance>true</includeInheritance>
34+
* <includeExamples>true</includeExamples>
35+
* <includeExtensionGuide>true</includeExtensionGuide>
36+
* </args>
37+
* </generator>
38+
* }
39+
*/
40+
public class MetaDataHtmlDocumentationGenerator extends SingleHtmlDirectGeneratorBase {
41+
42+
private static final Logger log = LoggerFactory.getLogger(MetaDataHtmlDocumentationGenerator.class);
43+
44+
// Configuration options
45+
private String version = "6.2.0";
46+
private String title = "MetaObjects Framework Documentation";
47+
private boolean includeInheritance = true;
48+
private boolean includeExamples = true;
49+
private boolean includeExtensionGuide = true;
50+
51+
public MetaDataHtmlDocumentationGenerator() {
52+
super();
53+
log.debug("Initialized HTML documentation generator with registry-based type discovery");
54+
}
55+
56+
@Override
57+
protected MetaDataHtmlDocumentationWriter getWriter(MetaDataLoader loader, OutputStream os) throws GeneratorIOException {
58+
try {
59+
return new MetaDataHtmlDocumentationWriter(loader, os)
60+
.withVersion(version)
61+
.withTitle(title)
62+
.withInheritance(includeInheritance)
63+
.withExamples(includeExamples)
64+
.withExtensionGuide(includeExtensionGuide);
65+
} catch (Exception e) {
66+
throw new RuntimeException("Failed to create HTML documentation writer", e);
67+
}
68+
}
69+
70+
/**
71+
* Configure the version string for the generated documentation
72+
*
73+
* @param version Version string (default: "6.2.0")
74+
*/
75+
public void setVersion(String version) {
76+
this.version = version;
77+
log.debug("Set documentation version to: {}", version);
78+
}
79+
80+
/**
81+
* Configure the title for the generated documentation
82+
*
83+
* @param title Documentation title (default: "MetaObjects Framework Documentation")
84+
*/
85+
public void setTitle(String title) {
86+
this.title = title;
87+
log.debug("Set documentation title to: {}", title);
88+
}
89+
90+
/**
91+
* Configure whether to include inheritance hierarchy analysis
92+
*
93+
* @param includeInheritance true to include inheritance visualization (default: true)
94+
*/
95+
public void setIncludeInheritance(boolean includeInheritance) {
96+
this.includeInheritance = includeInheritance;
97+
log.debug("Set includeInheritance to: {}", includeInheritance);
98+
}
99+
100+
/**
101+
* Configure whether to include usage examples for types
102+
*
103+
* @param includeExamples true to include usage examples (default: true)
104+
*/
105+
public void setIncludeExamples(boolean includeExamples) {
106+
this.includeExamples = includeExamples;
107+
log.debug("Set includeExamples to: {}", includeExamples);
108+
}
109+
110+
/**
111+
* Configure whether to include extension guide for plugin developers
112+
*
113+
* @param includeExtensionGuide true to include extension guide (default: true)
114+
*/
115+
public void setIncludeExtensionGuide(boolean includeExtensionGuide) {
116+
this.includeExtensionGuide = includeExtensionGuide;
117+
log.debug("Set includeExtensionGuide to: {}", includeExtensionGuide);
118+
}
119+
120+
@Override
121+
public String toString() {
122+
return "MetaDataHtmlDocumentationGenerator{" +
123+
"version='" + version + '\'' +
124+
", title='" + title + '\'' +
125+
", includeInheritance=" + includeInheritance +
126+
", includeExamples=" + includeExamples +
127+
", includeExtensionGuide=" + includeExtensionGuide +
128+
'}';
129+
}
130+
131+
/**
132+
* Get configuration summary for logging and debugging
133+
*
134+
* @return Human-readable configuration summary
135+
*/
136+
public String getConfigurationSummary() {
137+
StringBuilder summary = new StringBuilder();
138+
summary.append("HTML Documentation Generator Configuration:\n");
139+
summary.append(" Title: ").append(title).append("\n");
140+
summary.append(" Version: ").append(version).append("\n");
141+
summary.append(" Inheritance Analysis: ").append(includeInheritance ? "Enabled" : "Disabled").append("\n");
142+
summary.append(" Usage Examples: ").append(includeExamples ? "Enabled" : "Disabled").append("\n");
143+
summary.append(" Extension Guide: ").append(includeExtensionGuide ? "Enabled" : "Disabled");
144+
return summary.toString();
145+
}
146+
147+
///////////////////////////////////////////////////
148+
// Specialized HTML Documentation Features
149+
150+
/**
151+
* HTML documentation generation attribute constants for enhanced documentation
152+
*/
153+
public static final String HTML_TITLE = "htmlTitle";
154+
public static final String HTML_DESCRIPTION = "htmlDescription";
155+
public static final String HTML_EXAMPLE = "htmlExample";
156+
public static final String HTML_USAGE_PATTERN = "htmlUsagePattern";
157+
public static final String HTML_EXTENSION_GUIDE = "htmlExtensionGuide";
158+
public static final String HTML_SEE_ALSO = "htmlSeeAlso";
159+
public static final String HTML_SINCE_VERSION = "htmlSinceVersion";
160+
public static final String HTML_DEPRECATED = "htmlDeprecated";
161+
162+
/**
163+
* Registers HTML Documentation generation attributes for enhanced documentation.
164+
* Can be called by plugins to add rich documentation metadata to their types.
165+
*/
166+
public static void registerHtmlDocAttributes(com.draagon.meta.registry.MetaDataRegistry registry) {
167+
// Object-level HTML Documentation attributes
168+
registry.findType("object", "base")
169+
.optionalAttribute(HTML_TITLE, "string")
170+
.optionalAttribute(HTML_DESCRIPTION, "string")
171+
.optionalAttribute(HTML_EXAMPLE, "string")
172+
.optionalAttribute(HTML_USAGE_PATTERN, "string")
173+
.optionalAttribute(HTML_EXTENSION_GUIDE, "string")
174+
.optionalAttribute(HTML_SEE_ALSO, "string")
175+
.optionalAttribute(HTML_SINCE_VERSION, "string")
176+
.optionalAttribute(HTML_DEPRECATED, "string");
177+
178+
// Field-level HTML Documentation attributes
179+
registry.findType("field", "base")
180+
.optionalAttribute(HTML_TITLE, "string")
181+
.optionalAttribute(HTML_DESCRIPTION, "string")
182+
.optionalAttribute(HTML_EXAMPLE, "string")
183+
.optionalAttribute(HTML_USAGE_PATTERN, "string")
184+
.optionalAttribute(HTML_SEE_ALSO, "string")
185+
.optionalAttribute(HTML_SINCE_VERSION, "string")
186+
.optionalAttribute(HTML_DEPRECATED, "string");
187+
188+
// Enhanced examples for specific field types
189+
registry.findType("field", "string")
190+
.optionalAttribute(HTML_EXAMPLE, "string")
191+
.optionalAttribute(HTML_USAGE_PATTERN, "string");
192+
193+
registry.findType("field", "int")
194+
.optionalAttribute(HTML_EXAMPLE, "string")
195+
.optionalAttribute(HTML_USAGE_PATTERN, "string");
196+
197+
log.info("Registered HTML documentation attributes for enhanced type documentation");
198+
}
199+
}

0 commit comments

Comments
 (0)