Merge pull request #7 from dcm4che/dev

Improve JavaDocs of IODs
dcm4che · May 2, 2023 · d4ba898 · d4ba898
2 parents 9cd4f7c + f221cf1
commit d4ba898
Show file tree

Hide file tree

Showing 17 changed files with 237 additions and 134 deletions.
diff --git a/README.MD b/README.MD
@@ -25,7 +25,7 @@ repositories {
 
 ```groovy
 dependencies {
-    implementation 'org.dcm4che:dcm4che-typeddicom-lib-std:0.5.1'
+    implementation 'org.dcm4che:dcm4che-typeddicom-lib-std:0.5.2'
 }
 ```
 
@@ -41,7 +41,7 @@ repositories {
 
 ```kotlin
 dependencies {
-    implementation("org.dcm4che:dcm4che-typeddicom-lib-std:0.5.1")
+    implementation("org.dcm4che:dcm4che-typeddicom-lib-std:0.5.2")
 }
 ```
 
@@ -60,7 +60,7 @@ dependencies {
 <dependency>
     <groupId>org.dcm4che</groupId>
     <artifactId>dcm4che-typeddicom</artifactId>
-    <version>0.5.1</version>
+    <version>0.5.2</version>
 </dependency>
 ```
 ### Use private tags with the gradle plugin
@@ -78,7 +78,7 @@ buildscript {
 
 plugins {
     id 'java-library'
-    id 'org.dcm4che.typeddicom-java-generator' version '0.5.1'
+    id 'org.dcm4che.typeddicom-java-generator' version '0.5.2'
 }
 
 generateTypeddicomJavaSources {
@@ -99,7 +99,7 @@ buildscript {
 
 plugins {
     id("java-library")
-    id("org.dcm4che.typeddicom-java-generator") version "0.5.1"
+    id("org.dcm4che.typeddicom-java-generator") version "0.5.2"
 }
 
 generateTypeddicomJavaSources {

diff --git a/dcm4che-typeddicom-generator/dcm4che-typeddicom-java-generator-lib/build.gradle.kts b/dcm4che-typeddicom-generator/dcm4che-typeddicom-java-generator-lib/build.gradle.kts
@@ -28,11 +28,8 @@ dependencies {
 
     implementation("org.dcm4che:dcm4che-core:5.29.0")
 
-    implementation("org.jsoup:jsoup:1.14.3")
-
     implementation("com.fasterxml.jackson.core:jackson-core:2.14.2")
     implementation("com.fasterxml.jackson.core:jackson-databind:2.14.2")
-    implementation("com.fasterxml.jackson.core:jackson-annotations:2.14.2")
     implementation("com.fasterxml.jackson.dataformat:jackson-dataformat-yaml:2.14.2")
 
     testImplementation("org.junit.jupiter:junit-jupiter-api:5.7.0")

diff --git a/...dicom-java-generator-lib/src/main/java/org/dcm4che/typeddicom/generator/JavaDocUtils.java b/...dicom-java-generator-lib/src/main/java/org/dcm4che/typeddicom/generator/JavaDocUtils.java
@@ -0,0 +1,31 @@
+package org.dcm4che.typeddicom.generator;
+
+import org.davidmoten.text.utils.WordWrap;
+
+public class JavaDocUtils {
+    private static final String JAVA_DOC_NEWLINE = "\n * ";
+    private static final int MAX_LINE_LENGTH = 120;
+    private static final String ZERO_WIDTH_CHARACTERS_REGEX = "[\n\r]";
+
+    private JavaDocUtils() {
+    }
+
+    public static String javaDocify(String html, int indentationLevel) {
+        String jdoc = WordWrap.from(html)
+                .maxWidth(MAX_LINE_LENGTH
+                        - JAVA_DOC_NEWLINE.replaceAll(ZERO_WIDTH_CHARACTERS_REGEX, "").length()
+                        - indentationLevel)
+                .extraWordChars("0123456789-._~:/?#[]@!$&'()*+,;%=\"<>")
+                .newLine(JAVA_DOC_NEWLINE)
+                .breakWords(false)
+                .wrap();
+        jdoc = "/**\n * " + jdoc + "\n */";
+        jdoc = indent(jdoc, indentationLevel);
+        return jdoc;
+    }
+
+    private static String indent(String text, int indentationLevel) {
+        String indent = " ".repeat(indentationLevel * 4);
+        return indent + text.replace("\n", "\n" + indent);
+    }
+}
diff --git a/...c/main/java/org/dcm4che/typeddicom/generator/model/mustache/DataElementMustacheModel.java b/...c/main/java/org/dcm4che/typeddicom/generator/model/mustache/DataElementMustacheModel.java
@@ -2,23 +2,18 @@
 
 
 import com.fasterxml.jackson.annotation.JsonIgnore;
-import org.davidmoten.text.utils.WordWrap;
+import org.dcm4che.typeddicom.generator.JavaDocUtils;
+import org.dcm4che.typeddicom.parser.HtmlUtils;
 import org.dcm4che.typeddicom.parser.metamodel.dto.AdditionalAttributeInfoContextsDTO;
 import org.dcm4che.typeddicom.parser.metamodel.dto.AdditionalAttributeInfoDTO;
 import org.dcm4che.typeddicom.parser.metamodel.dto.DataElementMetaInfoDTO;
-import org.jsoup.Jsoup;
-import org.jsoup.nodes.Document;
-import org.jsoup.nodes.Element;
 
 import java.util.List;
 import java.util.Objects;
 import java.util.stream.Collectors;
 
 public final class DataElementMustacheModel {
     private static final String LINE_BREAK = "<br>";
-    private static final String JAVA_DOC_NEWLINE = "\n * ";
-    private static final int MAX_LINE_LENGTH = 120;
-    public static final String ZERO_WIDTH_CHARACTERS_REGEX = "[\n\r]";
     private final String keyword;
     private final String name;
     private final String privateCreatorConstant;
@@ -77,12 +72,10 @@ public DataElementMustacheModel(String keyword, DataElementMetaInfoDTO dto) {
         );
     }
 
-    @JsonIgnore
     public boolean isSequence() {
         return valueRepresentation.equals("Sequence");
     }
 
-    @JsonIgnore
     public String getValueRepresentationWrapper() {
         if (valueMultiplicity().equals("1")) {
             return valueRepresentation + "Wrapper";
@@ -91,40 +84,27 @@ public String getValueRepresentationWrapper() {
         }
     }
 
-    @JsonIgnore
     public String implementsBuilderInterfaces() {
         return contains.stream()
                 .map(key -> key + ".Builder<Builder, Item>")
                 .collect(Collectors.joining(", "));
     }
 
-    @JsonIgnore
     public String implementsHolderInterfaces() {
         return contains.stream().map(key -> key + ".Holder").collect(Collectors.joining(", "));
     }
 
-    @JsonIgnore
     public String classJavaDoc() {
         StringBuilder htmlBuilder = new StringBuilder();
         appendGeneralInfo(htmlBuilder);
         appendContextInfo(htmlBuilder);
-        Document jsoupDoc = Jsoup.parse(htmlBuilder.toString());
-        Document.OutputSettings outputSettings = new Document.OutputSettings();
-        outputSettings.prettyPrint(true);
-        jsoupDoc.select("br").after("\\n");
-        jsoupDoc.select("p").before("\\n");
-        jsoupDoc.outputSettings(outputSettings);
-        Element body = jsoupDoc.body();
-        sanitizeJDocHtml(body);
-        String htmlString = body.html();
-        htmlString = htmlString.replace("\\n", "\n");
-        htmlString = htmlString.replace("\n<br>", "<br>\n");
-        htmlString = htmlString.replaceAll("</p>(?!\\n)", "</p>\n");
+        String string = htmlBuilder.toString();
+        String htmlString = HtmlUtils.cleanUpHtml(string);
         if (retired) {
             htmlString += "\n\n@deprecated ";
             htmlString += comment;
         }
-        return javaDocify(htmlString, 0);
+        return JavaDocUtils.javaDocify(htmlString, 0);
     }
 
     private void appendGeneralInfo(StringBuilder html) {
@@ -156,38 +136,6 @@ private void appendContextInfo(StringBuilder html) {
         }
     }
 
-    private void sanitizeJDocHtml(Element body) {
-        for (Element element : body.select("dl > p")) {
-            assert element.parent() != null; // should always have a parent
-            element.parent().before(element);
-        }
-        for (Element element : body.select("p:empty")) {
-            element.remove();
-        }
-        for (Element element : body.select("dd:empty, dd:matchesOwn((?is))")) {
-            element.remove();
-        }
-    }
-
-    private String javaDocify(String html, int indentationLevel) {
-        String jdoc = WordWrap.from(html)
-                .maxWidth(MAX_LINE_LENGTH
-                        - JAVA_DOC_NEWLINE.replaceAll(ZERO_WIDTH_CHARACTERS_REGEX, "").length()
-                        - indentationLevel)
-                .extraWordChars("0123456789-._~:/?#[]@!$&'()*+,;%=\"<>")
-                .newLine(JAVA_DOC_NEWLINE)
-                .breakWords(false)
-                .wrap();
-        jdoc = "/**\n * " + jdoc + "\n */";
-        jdoc = indent(jdoc, indentationLevel);
-        return jdoc;
-    }
-
-    private String indent(String text, int indentationLevel) {
-        String indent = " ".repeat(indentationLevel * 4);
-        return indent + text.replace("\n", "\n" + indent);
-    }
-
     public String keyword() {
         return keyword;
     }

diff --git a/...dcm4che/typeddicom/generator/model/mustache/InformationObjectDefinitionMustacheModel.java b/...dcm4che/typeddicom/generator/model/mustache/InformationObjectDefinitionMustacheModel.java
@@ -1,5 +1,7 @@
 package org.dcm4che.typeddicom.generator.model.mustache;
 
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import org.dcm4che.typeddicom.generator.JavaDocUtils;
 import org.dcm4che.typeddicom.parser.metamodel.dto.InformationObjectDefinitionMetaInfoDTO;
 import org.dcm4che.typeddicom.parser.metamodel.dto.SOPClassDTO;
 
@@ -12,6 +14,7 @@ public final class InformationObjectDefinitionMustacheModel {
     private final String name;
     private final String href;
     private final String sectionId;
+    private final String description;
     private final List<SOPClassDTO> sopClasses;
     private final List<String> modules;
 
@@ -20,19 +23,22 @@ public InformationObjectDefinitionMustacheModel(
             String name,
             String href,
             String sectionId,
+            String description,
             List<SOPClassDTO> sopClasses,
             List<String> modules
     ) {
         this.keyword = keyword;
         this.name = name;
         this.href = href;
         this.sectionId = sectionId;
+        this.description = description;
         this.sopClasses = sopClasses;
         this.modules = modules;
     }
 
     public InformationObjectDefinitionMustacheModel(String key, InformationObjectDefinitionMetaInfoDTO dto) {
-        this(key, dto.getName(), dto.getHref(), dto.getSectionId(), dto.getSopClasses(), dto.getModules());
+        this(key, dto.getName(), dto.getHref(), dto.getSectionId(), dto.getDescription(), dto.getSopClasses(),
+                dto.getModules());
     }
 
     public String getImplementsModules() {
@@ -61,6 +67,10 @@ public String sectionId() {
         return sectionId;
     }
 
+    public String description() {
+        return description;
+    }
+
     public List<SOPClassDTO> sopClasses() {
         return sopClasses;
     }
@@ -69,6 +79,15 @@ public List<String> modules() {
         return modules;
     }
 
+    public String getClassJavaDoc() {
+        String javadocHtml = "<strong>Name:</strong> " + name + " <br>\n" +
+                "<strong>Description:</strong> <br>\n" + description + "\n" +
+                "\n" +
+                "@see <a href=\"" + href + "\">DICOM Standard Part 3 - " + name + "</a>";
+
+        return JavaDocUtils.javaDocify(javadocHtml, 0);
+    }
+
     @Override
     public boolean equals(Object obj) {
         if (obj == this) return true;
@@ -78,13 +97,14 @@ public boolean equals(Object obj) {
                 Objects.equals(this.name, that.name) &&
                 Objects.equals(this.href, that.href) &&
                 Objects.equals(this.sectionId, that.sectionId) &&
+                Objects.equals(this.description, that.description) &&
                 Objects.equals(this.sopClasses, that.sopClasses) &&
                 Objects.equals(this.modules, that.modules);
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(keyword, name, href, sectionId, sopClasses, modules);
+        return Objects.hash(keyword, name, href, sectionId, description, sopClasses, modules);
     }
 
     @Override
@@ -94,9 +114,8 @@ public String toString() {
                 "name=" + name + ", " +
                 "href=" + href + ", " +
                 "sectionId=" + sectionId + ", " +
+                "description=" + description + ", " +
                 "sopClasses=" + sopClasses + ", " +
                 "modules=" + modules + ']';
     }
-
-
 }
diff --git a/...4che-typeddicom-java-generator-lib/src/main/resources/templates/DataElement.java.mustache b/...4che-typeddicom-java-generator-lib/src/main/resources/templates/DataElement.java.mustache
@@ -254,8 +254,8 @@ public class {{keyword}} extends {{#sequence}}SequenceWrapper<{{keyword}}, {{key
         }
     }
 
-    public static class SimpleHolder extends AbstractAttributesWrapper implements Holder {
-        public SimpleHolder(Attributes attributes) {
+    static class SimpleHolder extends AbstractAttributesWrapper implements Holder {
+        private SimpleHolder(Attributes attributes) {
             super(attributes);
         }
     }

diff --git a/...java-generator-lib/src/main/resources/templates/InformationObjectDefinition.java.mustache b/...java-generator-lib/src/main/resources/templates/InformationObjectDefinition.java.mustache
@@ -13,12 +13,7 @@ import java.util.Collections;
 import java.util.HashSet;
 import java.util.Set;
 
-/**
- * <strong>Name:</strong> {{name}} <br>
- * <strong>Description:</strong> {{{description}}} <br>
- *
- * @see <a href="{{href}}">DICOM Standard Part 5 - {{name}}</a>
- */
+{{{classJavaDoc}}}
 public class {{keyword}} extends AbstractInformationObjectDefinition implements {{{implementsModules}}} {
     public static final Set<SOPClass> STANDARD_SOP_CLASSES;
     static {

diff --git a/...r/dcm4che-typeddicom-java-generator-lib/src/main/resources/templates/Module.java.mustache b/...r/dcm4che-typeddicom-java-generator-lib/src/main/resources/templates/Module.java.mustache
@@ -1,9 +1,11 @@
 // Auto generated
 package org.dcm4che.typeddicom.modules;
 
+import org.dcm4che.typeddicom.AbstractAttributesWrapper;
 {{#value.contains}}
 import org.dcm4che.typeddicom.dataelements.{{.}};
 {{/value.contains}}
+import org.dcm4che3.data.Attributes;
 
 /**
  * {{name}}
@@ -12,6 +14,16 @@ import org.dcm4che.typeddicom.dataelements.{{.}};
  *
  */
 public interface {{key}} extends {{{value.implementsHolderInterfaces}}} {
+    public static {{key}} wrap(Attributes attributes) {
+        return new SimpleWrapper(attributes);
+    }
+
+    static class SimpleWrapper extends AbstractAttributesWrapper implements {{key}} {
+        private SimpleWrapper(Attributes attributes) {
+            super(attributes);
+        }
+    }
+
     interface Builder<SELF extends Builder<SELF, T>, T extends {{key}}> extends {{{value.implementsBuilderInterfaces}}} {
     }
 }
diff --git a/dcm4che-typeddicom-parser/dcm4che-typeddicom-parser-dtos/build.gradle.kts b/dcm4che-typeddicom-parser/dcm4che-typeddicom-parser-dtos/build.gradle.kts
@@ -16,6 +16,8 @@ repositories {
 dependencies {
     implementation("com.fasterxml.jackson.core:jackson-annotations:2.14.2")
 
+    implementation("org.jsoup:jsoup:1.14.3")
+
     testImplementation(platform("org.junit:junit-bom:5.9.1"))
     testImplementation("org.junit.jupiter:junit-jupiter")
 }