Skip to content

Commit 3a6eccd

Browse files
jaredstehlerjaredstehler
committed
enhance jinjavadoc with support for snippets
1 parent 4d63d13 commit 3a6eccd

38 files changed

Lines changed: 405 additions & 406 deletions

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocExpTest.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
public class JinjavaDocExpTest extends JinjavaDocItem {
44

5-
public JinjavaDocExpTest(String name, String desc, String aliasOf, JinjavaDocParam... params) {
6-
super(name, desc, aliasOf, params);
5+
public JinjavaDocExpTest(String name, String desc, String aliasOf, JinjavaDocParam[] params, JinjavaDocSnippet[] snippets) {
6+
super(name, desc, aliasOf, params, snippets);
77
}
88

99
}

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocFactory.java‎

Lines changed: 24 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
import com.google.common.base.Throwables;
1111
import com.hubspot.jinjava.Jinjava;
1212
import com.hubspot.jinjava.doc.annotations.JinjavaParam;
13+
import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
1314
import com.hubspot.jinjava.lib.exptest.ExpTest;
1415
import com.hubspot.jinjava.lib.filter.Filter;
1516
import com.hubspot.jinjava.lib.fn.ELFunctionDefinition;
@@ -43,10 +44,11 @@ private void addExpTests(JinjavaDoc doc) {
4344

4445
if(docAnnotation == null) {
4546
LOG.warn("Expression Test {} doesn't have a @{} annotation", t.getName(), com.hubspot.jinjava.doc.annotations.JinjavaDoc.class.getName());
46-
doc.addExpTest(new JinjavaDocExpTest(t.getName(), "", ""));
47+
doc.addExpTest(new JinjavaDocExpTest(t.getName(), "", "", new JinjavaDocParam[]{}, new JinjavaDocSnippet[]{}));
4748
}
4849
else if(!docAnnotation.hidden()) {
49-
doc.addExpTest(new JinjavaDocExpTest(t.getName(), docAnnotation.value(), docAnnotation.aliasOf(), extractParams(docAnnotation.params())));
50+
doc.addExpTest(new JinjavaDocExpTest(t.getName(), docAnnotation.value(), docAnnotation.aliasOf(),
51+
extractParams(docAnnotation.params()), extractSnippets(docAnnotation.snippets())));
5052
}
5153
}
5254
}
@@ -57,10 +59,11 @@ private void addFilterDocs(JinjavaDoc doc) {
5759

5860
if(docAnnotation == null) {
5961
LOG.warn("Filter {} doesn't have a @{} annotation", f.getClass(), com.hubspot.jinjava.doc.annotations.JinjavaDoc.class.getName());
60-
doc.addFilter(new JinjavaDocFilter(f.getName(), "", ""));
62+
doc.addFilter(new JinjavaDocFilter(f.getName(), "", "", new JinjavaDocParam[]{}, new JinjavaDocSnippet[]{}));
6163
}
6264
else if(!docAnnotation.hidden()) {
63-
doc.addFilter(new JinjavaDocFilter(f.getName(), docAnnotation.value(), docAnnotation.aliasOf(), extractParams(docAnnotation.params())));
65+
doc.addFilter(new JinjavaDocFilter(f.getName(), docAnnotation.value(), docAnnotation.aliasOf(),
66+
extractParams(docAnnotation.params()), extractSnippets(docAnnotation.snippets())));
6467
}
6568
}
6669
}
@@ -81,10 +84,11 @@ private void addFnDocs(JinjavaDoc doc) {
8184

8285
if(docAnnotation == null) {
8386
LOG.warn("Function {} doesn't have a @{} annotation", fn.getName(), com.hubspot.jinjava.doc.annotations.JinjavaDoc.class.getName());
84-
doc.addFunction(new JinjavaDocFunction(fn.getLocalName(), "", ""));
87+
doc.addFunction(new JinjavaDocFunction(fn.getLocalName(), "", "", new JinjavaDocParam[]{}, new JinjavaDocSnippet[]{}));
8588
}
8689
else if(!docAnnotation.hidden()) {
87-
doc.addFunction(new JinjavaDocFunction(fn.getLocalName(), docAnnotation.value(), docAnnotation.aliasOf(), extractParams(docAnnotation.params())));
90+
doc.addFunction(new JinjavaDocFunction(fn.getLocalName(), docAnnotation.value(), docAnnotation.aliasOf(),
91+
extractParams(docAnnotation.params()), extractSnippets(docAnnotation.snippets())));
8892
}
8993
}
9094
}
@@ -99,10 +103,11 @@ private void addTagDocs(JinjavaDoc doc) {
99103

100104
if(docAnnotation == null) {
101105
LOG.warn("Tag {} doesn't have a @{} annotation", t.getName(), com.hubspot.jinjava.doc.annotations.JinjavaDoc.class.getName());
102-
doc.addTag(new JinjavaDocTag(t.getName(), StringUtils.isBlank(t.getEndTagName()), "", ""));
106+
doc.addTag(new JinjavaDocTag(t.getName(), StringUtils.isBlank(t.getEndTagName()), "", "", new JinjavaDocParam[]{}, new JinjavaDocSnippet[]{}));
103107
}
104108
else if(!docAnnotation.hidden()) {
105-
doc.addTag(new JinjavaDocTag(t.getName(), StringUtils.isBlank(t.getEndTagName()), docAnnotation.value(), docAnnotation.aliasOf(), extractParams(docAnnotation.params())));
109+
doc.addTag(new JinjavaDocTag(t.getName(), StringUtils.isBlank(t.getEndTagName()), docAnnotation.value(), docAnnotation.aliasOf(),
110+
extractParams(docAnnotation.params()), extractSnippets(docAnnotation.snippets())));
106111
}
107112
}
108113
}
@@ -118,4 +123,15 @@ private JinjavaDocParam[] extractParams(JinjavaParam[] params) {
118123
return result;
119124
}
120125

126+
private JinjavaDocSnippet[] extractSnippets(JinjavaSnippet[] snippets) {
127+
JinjavaDocSnippet[] result = new JinjavaDocSnippet[snippets.length];
128+
129+
for(int i = 0; i < snippets.length; i++) {
130+
JinjavaSnippet s = snippets[i];
131+
result[i] = new JinjavaDocSnippet(s.desc(), s.code(), s.output());
132+
}
133+
134+
return result;
135+
}
136+
121137
}

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocFilter.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
public class JinjavaDocFilter extends JinjavaDocItem {
44

5-
public JinjavaDocFilter(String name, String desc, String aliasOf, JinjavaDocParam... params) {
6-
super(name, desc, aliasOf, params);
5+
public JinjavaDocFilter(String name, String desc, String aliasOf, JinjavaDocParam[] params, JinjavaDocSnippet[] snippets) {
6+
super(name, desc, aliasOf, params, snippets);
77
}
88

99
}

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocFunction.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22

33
public class JinjavaDocFunction extends JinjavaDocItem {
44

5-
public JinjavaDocFunction(String name, String desc, String aliasOf, JinjavaDocParam... params) {
6-
super(name, desc, aliasOf, params);
5+
public JinjavaDocFunction(String name, String desc, String aliasOf, JinjavaDocParam[] params, JinjavaDocSnippet[] snippets) {
6+
super(name, desc, aliasOf, params, snippets);
77
}
88

99
}

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocItem.java‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,14 @@ public abstract class JinjavaDocItem {
66
private final String desc;
77
private final String aliasOf;
88
private final JinjavaDocParam[] params;
9+
private final JinjavaDocSnippet[] snippets;
910

10-
public JinjavaDocItem(String name, String desc, String aliasOf, JinjavaDocParam... params) {
11+
public JinjavaDocItem(String name, String desc, String aliasOf, JinjavaDocParam[] params, JinjavaDocSnippet[] snippets) {
1112
this.name = name;
1213
this.desc = desc;
1314
this.aliasOf = aliasOf;
1415
this.params = params;
16+
this.snippets = snippets;
1517
}
1618

1719
public String getName() {
@@ -30,4 +32,8 @@ public JinjavaDocParam[] getParams() {
3032
return params;
3133
}
3234

35+
public JinjavaDocSnippet[] getSnippets() {
36+
return snippets;
37+
}
38+
3339
}

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocSnippet.java‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
package com.hubspot.jinjava.doc;
2+
3+
public class JinjavaDocSnippet {
4+
5+
private final String desc;
6+
private final String code;
7+
private final String output;
8+
9+
public JinjavaDocSnippet(String desc, String code, String output) {
10+
this.desc = desc;
11+
this.code = code;
12+
this.output = output;
13+
}
14+
15+
public String getDesc() {
16+
return desc;
17+
}
18+
public String getCode() {
19+
return code;
20+
}
21+
public String getOutput() {
22+
return output;
23+
}
24+
25+
}

‎src/main/java/com/hubspot/jinjava/doc/JinjavaDocTag.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ public class JinjavaDocTag extends JinjavaDocItem {
44

55
private final boolean empty;
66

7-
public JinjavaDocTag(String name, boolean empty, String desc, String aliasOf, JinjavaDocParam... params) {
8-
super(name, desc, aliasOf, params);
7+
public JinjavaDocTag(String name, boolean empty, String desc, String aliasOf, JinjavaDocParam[] params, JinjavaDocSnippet[] snippets) {
8+
super(name, desc, aliasOf, params, snippets);
99
this.empty = empty;
1010
}
1111

‎src/main/java/com/hubspot/jinjava/doc/annotations/JinjavaDoc.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@
1212

1313
String value() default "";
1414
JinjavaParam[] params() default {};
15+
16+
JinjavaSnippet[] snippets() default {};
17+
1518
String aliasOf() default "";
1619
boolean hidden() default false;
1720

‎src/main/java/com/hubspot/jinjava/doc/annotations/JinjavaSnippet.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
package com.hubspot.jinjava.doc.annotations;
2+
3+
import java.lang.annotation.ElementType;
4+
import java.lang.annotation.Retention;
5+
import java.lang.annotation.RetentionPolicy;
6+
import java.lang.annotation.Target;
7+
8+
9+
@Retention(RetentionPolicy.RUNTIME)
10+
@Target({ ElementType.TYPE, ElementType.METHOD })
11+
public @interface JinjavaSnippet {
12+
String desc() default "";
13+
14+
String code();
15+
String output() default "";
16+
}

‎src/main/java/com/hubspot/jinjava/lib/exptest/IsEqualToExpTest.java‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,21 +4,23 @@
44

55
import com.hubspot.jinjava.doc.annotations.JinjavaDoc;
66
import com.hubspot.jinjava.doc.annotations.JinjavaParam;
7+
import com.hubspot.jinjava.doc.annotations.JinjavaSnippet;
78
import com.hubspot.jinjava.interpret.InterpretException;
89
import com.hubspot.jinjava.interpret.JinjavaInterpreter;
910

10-
1111
@JinjavaDoc(
12-
value="Check if an object has the same value as another object:\n\n" +
13-
14-
"{% if foo.expression is equalto 42 %}\n" +
15-
" the foo attribute evaluates to the constant 42\n" +
16-
"{% endif %}\n" +
17-
"This appears to be a useless test as it does exactly the same as the == operator, but it can be useful when used together with the selectattr function:\n" +
18-
19-
"{{ users|selectattr(\"email\", \"equalto\", \"foo@bar.invalid\") }}",
12+
value="Check if an object has the same value as another object",
2013
params={
2114
@JinjavaParam(value="other", type="object")
15+
},
16+
snippets={
17+
@JinjavaSnippet(
18+
code="{% if foo.expression is equalto 42 %}\n" +
19+
" the foo attribute evaluates to the constant 42\n" +
20+
"{% endif %}\n"),
21+
@JinjavaSnippet(
22+
desc="Usage with the selectattr filter",
23+
code="{{ users|selectattr(\"email\", \"equalto\", \"foo@bar.invalid\") }}"),
2224
})
2325
public class IsEqualToExpTest implements ExpTest {
2426

0 commit comments

Comments
 (0)