Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Frankdoc/210 note blocks #216

Merged
merged 7 commits into from
Sep 18, 2024
Merged

Frankdoc/210 note blocks #216

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b7b0da4
Parse @see tags and include them as quickLinks.
thomaspj10 Sep 12, 2024
7f02f17
Implement notes.
thomaspj10 Sep 12, 2024
645f7a0
Add an unit test and add the note to the XSD.
thomaspj10 Sep 12, 2024
a49f8ef
Allow javadoc tags in the notes.
thomaspj10 Sep 13, 2024
b66a02a
Merge master into this branch.
thomaspj10 Sep 17, 2024
0a3c219
Add missing less than to test and make formatting for the XSD a bit m…
thomaspj10 Sep 17, 2024
4f8c1a1
Merge master
thomaspj10 Sep 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 14 additions & 3 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/DocWriterNew.java
View file
Open in desktop
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Waarschijnlijk kan jij er niets aan doen, maar waarom heet dit ding DocWriterNew? Ik zie nergens *Old ..

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ik las daar net toevallig een stukje over in de code:

Quote:

 * This package contains a set of model classes that is used by {@link org.frankframework.frankdoc.DocWriterNew} to generate the
 * XML configuration schema used by Frank developers. Please note that {@link org.frankframework.frankdoc.DocWriterNew} is
 * presently not used; this class is under development.

Dit is nu natuurlijk niet het geval meer. Er zijn een aantal classes die zo gek heten dus ik zal er een issue voor aanmaken.

Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@
import org.frankframework.frankdoc.model.FrankAttribute;
import org.frankframework.frankdoc.model.FrankDocModel;
import org.frankframework.frankdoc.model.FrankElement;
import org.frankframework.frankdoc.model.Note;
import org.frankframework.frankdoc.model.ObjectConfigChild;
import org.frankframework.frankdoc.model.TextConfigChild;
import org.frankframework.frankdoc.util.LogUtil;
Expand Down Expand Up @@ -762,9 +763,19 @@ private void addElementTypeRefToElementGroup(XmlBuilder context, FrankElement fr

private void addDocumentationFrom(XmlBuilder element, FrankElement frankElement) {
if(version == XsdVersion.STRICT) {
String elementDescription = frankElement.getDescription();
if(! StringUtils.isBlank(elementDescription)) {
addDocumentation(element, elementDescription);
if (!StringUtils.isBlank(frankElement.getDescription())) {
StringBuilder description = new StringBuilder(frankElement.getDescription());

for (Note note : frankElement.getNotes()) {
description.append("<br><b>")
.append(note.type().name())
.append("</b>")
.append("<p>")
.append(note.value())
.append("</p>");
}

addDocumentation(element, description.toString());
}
}
}
Expand Down
11 changes: 1 addition & 10 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/DocWriterNewXmlUtils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ static XmlBuilder createAttributeWithType(String name) {
}

static void addDocumentation(XmlBuilder context, String description) {
description = checkedFlatten(description);
description = Utils.flattenJavaDocLinksToLastWords(description);
XmlBuilder annotation = addAnnotation(context);
XmlBuilder documentation = new XmlBuilder("documentation", "xs", XML_SCHEMA_URI);
annotation.addSubElement(documentation);
Expand All @@ -262,15 +262,6 @@ private static XmlBuilder addAnnotation(XmlBuilder context) {
return annotation;
}

private static String checkedFlatten(String text) {
try {
return Utils.flattenJavaDocLinksToLastWords(text);
} catch(FrankDocException e) {
log.error("Error flattening JavaDoc link in [{}]", text, e);
return text;
}
}

static XmlBuilder addGroup(XmlBuilder context, String name) {
XmlBuilder group = new XmlBuilder("group", "xs", XML_SCHEMA_URI);
context.addSubElement(group);
Expand Down
12 changes: 12 additions & 0 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/FrankDocJsonFactory.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -280,6 +280,18 @@ private JsonObject getElement(FrankElement frankElement) throws JsonException {
});
result.add("links", builder.build());
}
if (!frankElement.getNotes().isEmpty()) {
final var builder = bf.createArrayBuilder();
frankElement.getNotes().forEach(note -> {
final var noteBuilder = bf.createObjectBuilder();

noteBuilder.add("type", note.type().name());
noteBuilder.add("value", note.value());

builder.add(noteBuilder);
});
result.add("notes", builder.build());
}
return result.build();
}

Expand Down
15 changes: 8 additions & 7 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/Utils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,15 +237,15 @@ public static String jsonPretty(String json) {
return sw.toString().trim();
}

public static String flattenJavaDocLinksToLastWords(String text) throws FrankDocException {
public static String flattenJavaDocLinksToLastWords(String text) {
return replacePattern(text, JAVADOC_LINK_START_DELIMITER, Utils::getLinkReplacement);
}

/**
* Replaces all instances of {@code patternStart}...} with a provided substitution. Allows for curly braces between
* the text as long as they are evenly matched (same amount of opening braces and closing braces).
*/
public static String replacePattern(String text, String patternStart, Function<String, String> substitution) throws FrankDocException {
public static String replacePattern(String text, String patternStart, Function<String, String> substitution) {
if (text == null) {
return null;
}
Expand All @@ -258,7 +258,8 @@ public static String replacePattern(String text, String patternStart, Function<S
int stopIndex = text.indexOf(JAVADOC_SUBSTITUTION_PATTERN_STOP_DELIMITER, startIndex);

if (stopIndex < 0) {
throw new FrankDocException(String.format("Unfinished JavaDoc {@ ...} pattern text [%s] at index [%d]", text, startIndex), null);
log.warn("Unfinished JavaDoc {@ ...} pattern text [{}] at index [{}]", text, startIndex);
break;
}

result.append(text, currentIndex, startIndex);
Expand Down Expand Up @@ -305,22 +306,22 @@ private static String getLinkReplacement(String linkBody) {
}


public static String substituteJavadocTags(String text, FrankClass context) throws FrankDocException {
public static String substituteJavadocTags(String text, FrankClass context) {
// Order matters here. {@literal}, {@value} and {@link} can be used inside {@code ...} blocks.
String step = replaceLiteralValue(text);
step = replaceFieldValue(step, context);
return replaceCodeValue(step);
}

private static String replaceLiteralValue(String text) throws FrankDocException {
private static String replaceLiteralValue(String text) {
return replacePattern(text, JAVADOC_LITERAL_START_DELIMITER, StringEscapeUtils::escapeHtml4);
}

private static String replaceCodeValue(String text) throws FrankDocException {
private static String replaceCodeValue(String text) {
return replacePattern(text, JAVADOC_CODE_START_DELIMITER, Utils::getCodeValueReplacement);
}

private static String replaceFieldValue(String text, FrankClass context) throws FrankDocException {
private static String replaceFieldValue(String text, FrankClass context) {
return replacePattern(text, JAVADOC_VALUE_START_DELIMITER, s -> getClassFieldValueReplacement(s, context));
}

Expand Down
7 changes: 1 addition & 6 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/feature/Default.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,12 +42,7 @@ public String valueOf(FrankMethod method) {
if(result == null) {
result = method.getJavaDocTag(TAG_DEFAULT);
}
try {
return Utils.substituteJavadocTags(result, method.getDeclaringClass());
} catch(FrankDocException e) {
log.error("Could not replace {@value ...} in [{}]", result);
return result;
}
return Utils.substituteJavadocTags(result, method.getDeclaringClass());
}

private String fromDefaultAnnotation(FrankMethod method) {
Expand Down
22 changes: 3 additions & 19 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/feature/Description.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,33 +56,17 @@ public String valueOf(FrankMethod method) {

result = result.replace(INHERIT_DOC_TAG, parentDoc == null ? "" : parentDoc).strip();
}
try {
return Utils.substituteJavadocTags(result, method.getDeclaringClass());
} catch(FrankDocException e) {
log.error("Could not replace javaDoc tags in [{}]", result);
return result;
}
return Utils.substituteJavadocTags(result, method.getDeclaringClass());
}

public String valueOf(FrankClass clazz) {
String result = clazz.getJavaDoc();
try {
return Utils.substituteJavadocTags(result, clazz);
} catch(FrankDocException e) {
log.error("Could not replace javaDoc tags in [{}]", result);
return result;
}
return Utils.substituteJavadocTags(clazz.getJavaDoc(), clazz);
}

public String valueOf(FrankEnumConstant enumConstant) {
String result = enumConstant.getJavaDoc();
if (!StringUtils.isBlank(result)) {
try {
return Utils.substituteJavadocTags(result, null);
} catch (FrankDocException e) {
log.error("Could not replace javaDoc tags in [{}]", result);
return result;
}
return Utils.substituteJavadocTags(result, null);
}

return null;
Expand Down
81 changes: 50 additions & 31 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/model/FrankElement.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@
import java.util.function.Predicate;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
import java.util.stream.Stream;

/**
* Models a Java class that can be referred to in a Frank configuration.
Expand All @@ -63,6 +64,10 @@ public class FrankElement implements Comparable<FrankElement> {
public static final String JAVADOC_FORWARDS_ANNOTATION_CLASSNAME = "org.frankframework.doc.Forwards";
public static final String JAVADOC_SEE = "@see";
public static final String JAVADOC_TAG = "@ff.tag";
public static final String JAVADOC_INFO_NOTE_TAG = "@ff.info";
public static final String JAVADOC_TIP_NOTE_TAG = "@ff.tip";
public static final String JAVADOC_WARNING_NOTE_TAG = "@ff.warning";
public static final String JAVADOC_DANGER_NOTE_TAG = "@ff.danger";
public static final String LABEL = "org.frankframework.doc.Label";
public static final String LABEL_NAME = "name";

Expand Down Expand Up @@ -105,35 +110,41 @@ public class FrankElement implements Comparable<FrankElement> {
private @Getter List<String> xmlElementNames;
private @Getter FrankElementStatistics statistics;
private LinkedHashMap<String, ConfigChildSet> configChildSets;
private @Getter @Setter String description;
private @Getter @Setter String descriptionHeader;
private @Getter String description;
private @Getter String descriptionHeader;
private @Getter String meaningOfParameters;
private @Getter List<ParsedJavaDocTag> specificParameters = new ArrayList<>();
private @Getter List<Forward> forwards = new ArrayList<>();
private @Getter List<QuickLink> quickLinks = new ArrayList<>();
private @Getter List<ParsedJavaDocTag> tags = new ArrayList<>();
private @Getter List<Note> notes = new ArrayList<>();

private @Getter List<FrankLabel> labels = new ArrayList<>();

FrankElement(FrankClass clazz, LabelValues labelValues) {
this(clazz.getName(), clazz.getSimpleName(), clazz.isAbstract());
deprecationInfo = Deprecated.getInstance().getInfo(clazz);
configChildSets = new LinkedHashMap<>();
this.completeFrankElement(clazz);

handleConfigChildSetterCandidates(clazz);
this.meaningOfParameters = parseParametersJavadocTag(clazz);
this.specificParameters = parseParameterJavadocTags(clazz);
this.forwards = parseForwardJavadocTags(clazz);
this.quickLinks = parseSeeJavadocTags(clazz);
this.tags = parseTagJavadocTags(clazz);
meaningOfParameters = parseParametersJavadocTag(clazz);
specificParameters = parseParameterJavadocTags(clazz);
forwards = parseForwardJavadocTags(clazz);
quickLinks = parseSeeJavadocTags(clazz);
tags = parseTagJavadocTags(clazz);
notes = parseNotesJavadocTags(clazz);
handleLabels(clazz, labelValues);

description = Description.getInstance().valueOf(clazz);
descriptionHeader = renderDescriptionHeader();
}

private void completeFrankElement(FrankClass clazz) {
setDescription(Description.getInstance().valueOf(clazz));
private String renderDescriptionHeader() {
if (getDescription() != null) {
setDescriptionHeader(calculateDescriptionHeader(getDescription()));
return calculateDescriptionHeader(getDescription());
}

return null;
}

static String calculateDescriptionHeader(String description) {
Expand Down Expand Up @@ -207,13 +218,7 @@ private List<ParsedJavaDocTag> parseParameterJavadocTags(FrankClass clazz) {
}

private String parseParametersJavadocTag(FrankClass clazz) {
try {
return Utils.substituteJavadocTags(clazz.getJavaDocTag(JAVADOC_PARAMETERS), clazz);
} catch(FrankDocException e) {
log.error("Error parsing the meaning of parameters", e);
}

return null;
return Utils.substituteJavadocTags(clazz.getJavaDocTag(JAVADOC_PARAMETERS), clazz);
}

private List<Forward> parseForwardJavadocTags(FrankClass clazz) {
Expand Down Expand Up @@ -254,22 +259,20 @@ private Forward annotationToForward(FrankAnnotation annotation) {

private List<QuickLink> parseSeeJavadocTags(FrankClass clazz) {
return clazz.getAllJavaDocTagsOf(JAVADOC_SEE).stream()
.map(this::tryParseQuickLink)
.filter(Objects::nonNull)
.toList();
}

private QuickLink tryParseQuickLink(String value) {
final var matcher = JAVADOC_SEE_PATTERN.matcher(value);
.map(value -> {
final var matcher = JAVADOC_SEE_PATTERN.matcher(value);

if (!matcher.matches()) {
return null;
}
if (!matcher.matches()) {
return null;
}

String label = matcher.group(2);
String url = matcher.group(1);
String label = matcher.group(2);
String url = matcher.group(1);

return new QuickLink(label, url);
return new QuickLink(label, url);
})
.filter(Objects::nonNull)
.toList();
}

private List<ParsedJavaDocTag> parseTagJavadocTags(FrankClass clazz) {
Expand All @@ -285,6 +288,22 @@ private List<ParsedJavaDocTag> parseTagJavadocTags(FrankClass clazz) {
return tags;
}

private List<Note> parseNotesJavadocTags(FrankClass clazz) {
return Stream.of(
parseNoteJavadocTags(clazz, JAVADOC_INFO_NOTE_TAG, NoteType.INFO),
parseNoteJavadocTags(clazz, JAVADOC_TIP_NOTE_TAG, NoteType.TIP),
parseNoteJavadocTags(clazz, JAVADOC_WARNING_NOTE_TAG, NoteType.WARNING),
parseNoteJavadocTags(clazz, JAVADOC_DANGER_NOTE_TAG, NoteType.DANGER)
).flatMap(Collection::stream)
.toList();
}

private List<Note> parseNoteJavadocTags(FrankClass clazz, String tagName, NoteType type) {
return clazz.getAllJavaDocTagsOf(tagName).stream()
.map(value -> new Note(type, Utils.substituteJavadocTags(value, clazz)))
.toList();
}

private List<ParsedJavaDocTag> parseJavadocTags(FrankClass clazz, String tagName) {
return clazz.getAllJavaDocTagsOf(tagName).stream()
.map(arguments -> {
Expand Down
22 changes: 22 additions & 0 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/model/Note.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
/*
Copyright 2024 WeAreFrank!

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package org.frankframework.frankdoc.model;

public record Note(NoteType type, String value) {
}


24 changes: 24 additions & 0 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/model/NoteType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
/*
Copyright 2024 WeAreFrank!
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

package org.frankframework.frankdoc.model;

public enum NoteType {
INFO,
TIP,
WARNING,
DANGER;
}
1 change: 1 addition & 0 deletions .../src/test/java/org/frankframework/frankdoc/DocWriterNewAndJsonGenerationExamplesTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,7 @@ public static Collection<Object[]> data() {
{XsdVersion.STRICT, AttributeTypeStrategy.ALLOW_PROPERTY_REF, "general-test-digester-rules.xml", "org.frankframework.frankdoc.testtarget.examples.unsafe.Unsafe", "unsafe.xsd", "unsafe.json"},
{XsdVersion.STRICT, AttributeTypeStrategy.ALLOW_PROPERTY_REF, "general-test-digester-rules.xml", "org.frankframework.frankdoc.testtarget.examples.inheritdoc.Child", "inheritdoc.xsd", "inheritdoc.json"},
{XsdVersion.STRICT, AttributeTypeStrategy.ALLOW_PROPERTY_REF, "general-test-digester-rules.xml", "org.frankframework.frankdoc.testtarget.see.See", null, "see.json"},
{XsdVersion.STRICT, AttributeTypeStrategy.ALLOW_PROPERTY_REF, "general-test-digester-rules.xml", "org.frankframework.frankdoc.testtarget.notes.Note", "notes.xsd", "notes.json"},
// Classes in package "org.frankframework.frankdoc.testtarget.examples.simple.name.conflict.second" are also added although that package is not shown in this table.
// See method getAllRequiredPackages().
{XsdVersion.STRICT, AttributeTypeStrategy.ALLOW_PROPERTY_REF, "general-test-digester-rules.xml", "org.frankframework.frankdoc.testtarget.examples.simple.name.conflict.first.Master", "nameConflictStrict.xsd", "nameConflict.json"},
Expand Down
Loading
Loading