From 4d2484e2adfe2d6aac84ee616f9620f77db91b4a Mon Sep 17 00:00:00 2001
From: Mathieu Baudier <mbaudier@argeo.org>
Date: Sat, 17 Jun 2023 07:04:25 +0200
Subject: [PATCH] Improve documentation.

---
 .../org/argeo/api/acr/search/AndFilter.java   |  1 +
 .../org/argeo/api/acr/search/BasicSearch.java | 18 ++++++++-----
 .../org/argeo/api/acr/search/Composition.java |  3 ++-
 .../org/argeo/api/acr/search/Constraint.java  |  1 +
 .../argeo/api/acr/search/ContentFilter.java   | 26 +++++++++----------
 .../argeo/api/acr/search/Intersection.java    |  3 ++-
 .../org/argeo/api/acr/search/OrFilter.java    |  1 +
 .../src/org/argeo/api/acr/search/Union.java   |  1 +
 .../cms/ux/acr/ContentHierarchicalPart.java   |  9 ++++---
 9 files changed, 37 insertions(+), 26 deletions(-)

diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/AndFilter.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/AndFilter.java
index e58b21236..d3880d899 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/AndFilter.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/AndFilter.java
@@ -1,5 +1,6 @@
 package org.argeo.api.acr.search;
 
+/** AND filter based on the intersection composition. */
 public class AndFilter extends ContentFilter<Intersection> {
 
 	public AndFilter() {
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/BasicSearch.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/BasicSearch.java
index 8028f5d20..2e4f249d4 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/BasicSearch.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/BasicSearch.java
@@ -9,9 +9,13 @@ import java.util.function.Consumer;
 
 import javax.xml.namespace.QName;
 
-import org.argeo.api.acr.DName;
 import org.argeo.api.acr.QNamed;
 
+/**
+ * A basic search mechanism modelled on WebDav basicsearch.
+ * 
+ * @see http://www.webdav.org/specs/rfc5323.html
+ */
 public class BasicSearch {
 
 	private List<QName> select = new ArrayList<>();
@@ -87,10 +91,10 @@ public class BasicSearch {
 
 	}
 
-	static void main(String[] args) {
-		BasicSearch search = new BasicSearch();
-		search.select(DName.creationdate.qName()) //
-				.from(URI.create("/test")) //
-				.where((f) -> f.eq(DName.creationdate.qName(), ""));
-	}
+//	static void main(String[] args) {
+//		BasicSearch search = new BasicSearch();
+//		search.select(DName.creationdate.qName()) //
+//				.from(URI.create("/test")) //
+//				.where((f) -> f.eq(DName.creationdate.qName(), ""));
+//	}
 }
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/Composition.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/Composition.java
index 80786f462..622d8c268 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/Composition.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/Composition.java
@@ -1,4 +1,5 @@
 package org.argeo.api.acr.search;
+
+/** Marker interface for a composition of multiple constraints. */
 interface Composition {
 }
-
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/Constraint.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/Constraint.java
index fc4313d7a..36c98f7a5 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/Constraint.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/Constraint.java
@@ -1,4 +1,5 @@
 package org.argeo.api.acr.search;
 
+/** Marker interface for a constraint. */
 public interface Constraint {
 }
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/ContentFilter.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/ContentFilter.java
index c5f5fc607..45f2d848c 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/ContentFilter.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/ContentFilter.java
@@ -6,9 +6,9 @@ import java.util.function.Consumer;
 
 import javax.xml.namespace.QName;
 
-import org.argeo.api.acr.DName;
 import org.argeo.api.acr.QNamed;
 
+/** A constraint filtering based ona given composition (and/or). */
 public abstract class ContentFilter<COMPOSITION extends Composition> implements Constraint {
 	private Set<Constraint> constraintss = new HashSet<>();
 
@@ -167,17 +167,17 @@ public abstract class ContentFilter<COMPOSITION extends Composition> implements
 
 	}
 
-	public static void main(String[] args) {
-		AndFilter filter = new AndFilter();
-		filter.eq(new QName("test"), "test").and().not().eq(new QName("type"), "integer");
-
-		OrFilter unionFilter = new OrFilter();
-		unionFilter.all((f) -> {
-			f.eq(DName.displayname, "").and().eq(DName.creationdate, "");
-		}).or().not().any((f) -> {
-			f.eq(DName.creationdate, "").or().eq(DName.displayname, "");
-		});
-
-	}
+//	public static void main(String[] args) {
+//		AndFilter filter = new AndFilter();
+//		filter.eq(new QName("test"), "test").and().not().eq(new QName("type"), "integer");
+//
+//		OrFilter unionFilter = new OrFilter();
+//		unionFilter.all((f) -> {
+//			f.eq(DName.displayname, "").and().eq(DName.creationdate, "");
+//		}).or().not().any((f) -> {
+//			f.eq(DName.creationdate, "").or().eq(DName.displayname, "");
+//		});
+//
+//	}
 
 }
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/Intersection.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/Intersection.java
index 5fff2ae88..9ce763204 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/Intersection.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/Intersection.java
@@ -1,4 +1,6 @@
 package org.argeo.api.acr.search;
+
+/** A composition which is the intersection of sets (AND). */
 class Intersection implements Composition {
 	ContentFilter<Intersection> filter;
 
@@ -12,4 +14,3 @@ class Intersection implements Composition {
 	}
 
 }
-
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/OrFilter.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/OrFilter.java
index 40460d499..80a1568be 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/OrFilter.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/OrFilter.java
@@ -1,5 +1,6 @@
 package org.argeo.api.acr.search;
 
+/** OR filter based on the union composition. */
 public class OrFilter extends ContentFilter<Union> {
 
 	public OrFilter() {
diff --git a/org.argeo.api.acr/src/org/argeo/api/acr/search/Union.java b/org.argeo.api.acr/src/org/argeo/api/acr/search/Union.java
index d4b342b5f..df1b00175 100644
--- a/org.argeo.api.acr/src/org/argeo/api/acr/search/Union.java
+++ b/org.argeo.api.acr/src/org/argeo/api/acr/search/Union.java
@@ -1,5 +1,6 @@
 package org.argeo.api.acr.search;
 
+/** A composition which is the union of sets (OR). */
 class Union implements Composition {
 	ContentFilter<Union> filter;
 
diff --git a/org.argeo.cms.ux/src/org/argeo/cms/ux/acr/ContentHierarchicalPart.java b/org.argeo.cms.ux/src/org/argeo/cms/ux/acr/ContentHierarchicalPart.java
index baaa25238..bb9c7422d 100644
--- a/org.argeo.cms.ux/src/org/argeo/cms/ux/acr/ContentHierarchicalPart.java
+++ b/org.argeo.cms.ux/src/org/argeo/cms/ux/acr/ContentHierarchicalPart.java
@@ -8,15 +8,16 @@ import org.argeo.api.acr.Content;
 import org.argeo.cms.ux.widgets.AbstractHierarchicalPart;
 import org.argeo.cms.ux.widgets.HierarchicalPart;
 
+/** A {@link HierarchicalPart} based on {@link Content}. */
 public class ContentHierarchicalPart extends AbstractHierarchicalPart<Content> implements HierarchicalPart<Content> {
 	@Override
-	public List<Content> getChildren(Content content) {
+	public List<Content> getChildren(Content parent) {
 		List<Content> res = new ArrayList<>();
-		if (isLeaf(content))
+		if (isLeaf(parent))
 			return res;
-		if (content == null)
+		if (parent == null)
 			return res;
-		for (Iterator<Content> it = content.iterator(); it.hasNext();) {
+		for (Iterator<Content> it = parent.iterator(); it.hasNext();) {
 			res.add(it.next());
 		}
 
-- 
2.30.2