You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by ah...@apache.org on 2020/12/09 15:00:09 UTC
[isis] branch master updated: ISIS-2473: use a more compact format,
excluding java source rendering
This is an automated email from the ASF dual-hosted git repository.
ahuber pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git
The following commit(s) were added to refs/heads/master by this push:
new bfeb85a ISIS-2473: use a more compact format, excluding java source rendering
bfeb85a is described below
commit bfeb85a97c590738998f37b6835c78f4897cf55e
Author: Andi Huber <ah...@apache.org>
AuthorDate: Wed Dec 9 15:59:53 2020 +0100
ISIS-2473: use a more compact format, excluding java source rendering
---
.../modules/generated/pages/index/RoleMemento.adoc | 10 ++---
.../modules/generated/pages/index/UserMemento.adoc | 44 +++++++++----------
.../modules/generated/pages/index/UserService.adoc | 34 +++++++--------
.../apache/isis/tooling/cli/doclet/Adoclet.java | 51 ++++++++++++----------
.../isis/tooling/cli/doclet/AdocletContext.java | 18 ++++++++
.../apache/isis/tooling/cli/doclet/ToAsciiDoc.java | 2 +-
.../isis/tooling/cli/projdoc/ProjectDocModel.java | 2 +-
.../isis/tooling/cli/test/doclet/AdocletTest.java | 2 +-
8 files changed, 88 insertions(+), 75 deletions(-)
diff --git a/antora/components/system/modules/generated/pages/index/RoleMemento.adoc b/antora/components/system/modules/generated/pages/index/RoleMemento.adoc
index 5aae575..e246828 100644
--- a/antora/components/system/modules/generated/pages/index/RoleMemento.adoc
+++ b/antora/components/system/modules/generated/pages/index/RoleMemento.adoc
@@ -1,13 +1,9 @@
-= RoleMemento
+= RoleMemento : _class_
+
+
Immutable serializable value held by xref:system:generated:index/UserMemento.adoc[UserMemento] .
-.RoleMemento
-[source,java]
-----
-class RoleMemento {
-}
-----
diff --git a/antora/components/system/modules/generated/pages/index/UserMemento.adoc b/antora/components/system/modules/generated/pages/index/UserMemento.adoc
index 054d042..e171d3c 100644
--- a/antora/components/system/modules/generated/pages/index/UserMemento.adoc
+++ b/antora/components/system/modules/generated/pages/index/UserMemento.adoc
@@ -1,36 +1,32 @@
-= UserMemento
+= UserMemento : _class_
-Immutable serializable value holding details about a user and its roles.
-
-.UserMemento
-[source,java]
-----
-class UserMemento {
-
- UserMemento system() // <.>
- UserMemento ofName(@NonNull final String name) // <.>
- UserMemento ofNameAndRoles(@NonNull final String name, final RoleMemento... roles) // <.>
-
- UserMemento ofNameAndRoleNames(@NonNull final String name, final String... roleNames) // <.>
-
- UserMemento ofNameAndRoleNames(@NonNull final String name, @NonNull final Stream<String> roleNames) // <.>
+Immutable serializable value holding details about a user and its roles.
- boolean isCurrentUser(@Nullable final String userName) // <.>
-}
-----
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] system()` The framework's internal user with unrestricted privileges.
+* `*system*()` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+The framework's internal user with unrestricted privileges.
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] ofName(String name)` Creates a new user with the specified name and no roles.
+* `*ofName*(String name)` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+Creates a new user with the specified name and no roles.
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] ofNameAndRoles(String name, xref:system:generated:index/RoleMemento.adoc[RoleMemento]... roles)` Creates a new user with the specified name and assigned roles.
+* `*ofNameAndRoles*(String name, xref:system:generated:index/RoleMemento.adoc[RoleMemento]... roles)` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+Creates a new user with the specified name and assigned roles.
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] ofNameAndRoleNames(String name, String... roleNames)` Creates a new user with the specified name and assigned role names.
+* `*ofNameAndRoleNames*(String name, String... roleNames)` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+Creates a new user with the specified name and assigned role names.
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] ofNameAndRoleNames(String name, Stream<String> roleNames)` Creates a new user with the specified name and assigned role names.
+* `*ofNameAndRoleNames*(String name, Stream<String> roleNames)` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+Creates a new user with the specified name and assigned role names.
-<.> `boolean isCurrentUser(String userName)` Determine if the specified name is this user.
+* `*isCurrentUser*(String userName)` : `boolean`
++
+Determine if the specified name is this user.
diff --git a/antora/components/system/modules/generated/pages/index/UserService.adoc b/antora/components/system/modules/generated/pages/index/UserService.adoc
index d6b8572..4f2979f 100644
--- a/antora/components/system/modules/generated/pages/index/UserService.adoc
+++ b/antora/components/system/modules/generated/pages/index/UserService.adoc
@@ -1,4 +1,6 @@
-= UserService
+= UserService : _interface_
+
+
The xref:system:generated:index/UserService.adoc[UserService] allows the domain object to obtain the identity of the user
interacting with said object.
@@ -7,29 +9,23 @@ interacting with said object.
If _SudoService_ has been used to temporarily override the user and/or roles,
then this service will report the overridden values instead.
-.UserService
-[source,java]
-----
-interface UserService {
-
- Optional<UserMemento> currentUser() // <.>
-
- UserMemento getUser() // <.>
-
- UserMemento currentUserElseFail() // <.>
-
- Optional<String> currentUserName() // <.>
-}
-----
-<.> `Optional<xref:system:generated:index/UserMemento.adoc[UserMemento]> currentUser()` Optionally gets the details about the current user,
+* `*currentUser*()` : `Optional<xref:system:generated:index/UserMemento.adoc[UserMemento]>`
++
+Optionally gets the details about the current user,
based on whether an _ExecutionContext_ can be found with the current thread's context.
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] getUser()` Gets the details about the current user.
+* `*getUser*()` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+Gets the details about the current user.
-<.> `xref:system:generated:index/UserMemento.adoc[UserMemento] currentUserElseFail()` Gets the details about the current user.
+* `*currentUserElseFail*()` : `xref:system:generated:index/UserMemento.adoc[UserMemento]`
++
+Gets the details about the current user.
-<.> `Optional<String> currentUserName()` Optionally gets the the current user's name,
+* `*currentUserName*()` : `Optional<String>`
++
+Optionally gets the the current user's name,
based on whether an _ExecutionContext_ can be found with the current thread's context.
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/Adoclet.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/Adoclet.java
index d032859..d159443 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/Adoclet.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/Adoclet.java
@@ -77,7 +77,7 @@ public class Adoclet {
val introBlock = AsciiDocFactory.block(doc);
val javaSourceBlock = AsciiDocFactory.block(doc);
- val footNoteBlock = AsciiDocFactory.block(doc);
+ val methodDescriptionBlock = AsciiDocFactory.block(doc);
val mds = TypeDeclarations.streamPublicMethodDeclarations(td)
.filter(Javadocs::presentAndNotHidden)
@@ -93,43 +93,50 @@ public class Adoclet {
// -- java content
- val java = new StringBuilder();
+ if(docletContext.isIncludeJavaSource()) {
- java.append(String.format("%s %s {\n",
- getDeclarationKeyword(),
- td.getName().asString()));
-
- mds.forEach(md->{
-
- java.append(String.format("\n %s // <.>\n",
- Adoclets.toNormalizedMethodDeclaration(md)));
+ val java = new StringBuilder();
- });
-
- java.append("}\n");
-
- javaSourceBlock.setSource(
- AsciiDocFactory.SourceFactory.java(java.toString(), td.getName().asString()));
-
- // -- foot notes
+ java.append(String.format("%s %s {\n",
+ getDeclarationKeyword(),
+ td.getName().asString()));
+
+ mds.forEach(md->{
+
+ java.append(String.format("\n %s // <.>\n",
+ Adoclets.toNormalizedMethodDeclaration(md)));
+
+ });
+
+ java.append("}\n");
+
+ javaSourceBlock.setSource(
+ AsciiDocFactory.SourceFactory.java(java.toString(), td.getName().asString()));
+ }
+
+ // -- method descriptions
- val footNotes = new StringBuilder();
+ val methodDescriptions = new StringBuilder();
mds.forEach(md->{
md.getJavadoc()
.ifPresent(javadoc->{
- footNotes.append(String.format("\n<.> %s %s\n",
+ methodDescriptions.append(String.format(docletContext.getMethodDescriptionFormat(),
toAdocConverter.methodDeclaration(md),
toAdocConverter.javadoc(javadoc)));
});
});
- footNoteBlock.setSource(footNotes.toString());
+ methodDescriptionBlock.setSource(methodDescriptions.toString());
try {
- doc.setTitle(td.getName().asString());
+ val title = String.format("%s : _%s_\n\n",
+ td.getName().asString(),
+ getDeclarationKeyword());
+
+ doc.setTitle(title);
return AsciiDocWriter.toString(doc);
} catch (IOException e) {
e.printStackTrace();
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/AdocletContext.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/AdocletContext.java
index 18090ea..4b5603d 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/AdocletContext.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/AdocletContext.java
@@ -38,6 +38,15 @@ public class AdocletContext {
private final @NonNull String xrefPageIdFormat;
+ @Builder.Default
+ private final @NonNull String methodFormat = "`%s %s(%s)`"; // return-type | name | param-list
+
+ @Builder.Default
+ private final @NonNull String methodDescriptionFormat = "\n<.> %s %s\n"; // method | description
+
+ @Builder.Default
+ private final boolean includeJavaSource = true;
+
private final Map<String, Adoclet> adocletIndex = _Maps.newTreeMap();
public AdocletContext add(final @NonNull Adoclet adoclet) {
@@ -67,4 +76,13 @@ public class AdocletContext {
return Optional.ofNullable(adocletIndex.get(key));
}
+ public static AdocletContextBuilder compactFormat() {
+ return AdocletContext.builder()
+ .xrefPageIdFormat("system:generated:index/%s.adoc")
+ .methodFormat("`*%2$s*(%3$s)` : `%1$s`") // return-type | name | param-list)
+ .methodDescriptionFormat("\n* %s\n+\n%s\n") // method | description
+ .includeJavaSource(false)
+ ;
+ }
+
}
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/ToAsciiDoc.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/ToAsciiDoc.java
index 7538138..c95eb08 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/ToAsciiDoc.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/doclet/ToAsciiDoc.java
@@ -38,7 +38,7 @@ class ToAsciiDoc {
private final AdocletContext docletContext;
public String methodDeclaration(final @NonNull MethodDeclaration md) {
- return String.format("`%s %s(%s)`",
+ return String.format(docletContext.getMethodFormat(),
type(md.getType()),
md.getNameAsString(),
md.getParameters()
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java
index e55d252..9ed0d47 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java
@@ -87,7 +87,7 @@ public class ProjectDocModel {
modules = new TreeSet<ProjectNode>();
projTree.depthFirst(modules::add);
- val docletContext = AdocletContext.builder()
+ val docletContext = AdocletContext.compactFormat()
.xrefPageIdFormat(cliConfig.getDocletXrefPageIdFormat())
.build();
diff --git a/tooling/cli/src/test/java/org/apache/isis/tooling/cli/test/doclet/AdocletTest.java b/tooling/cli/src/test/java/org/apache/isis/tooling/cli/test/doclet/AdocletTest.java
index 9352718..4cac61d 100644
--- a/tooling/cli/src/test/java/org/apache/isis/tooling/cli/test/doclet/AdocletTest.java
+++ b/tooling/cli/src/test/java/org/apache/isis/tooling/cli/test/doclet/AdocletTest.java
@@ -39,7 +39,7 @@ class AdocletTest {
val projDir = new File("./").getAbsoluteFile();
val analyzerConfig = AnalyzerConfigFactory.mavenTest(projDir, Language.JAVA).main();
- val docletContext = AdocletContext.builder()
+ val docletContext = AdocletContext.compactFormat()
.xrefPageIdFormat("system:generated:index/%s.adoc")
.build();