From 83255431f7bf2bcccfe59333a1f77ca71c3035e1 Mon Sep 17 00:00:00 2001
From: Benjamin Davies <bentendavies@gmail.com>
Date: Wed, 20 Mar 2024 16:08:43 +1300
Subject: [PATCH] Document purpose of shared methods

---
 .../plantuml/cheneer/ChenEerDiagram.java      | 23 +++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/net/sourceforge/plantuml/cheneer/ChenEerDiagram.java b/src/net/sourceforge/plantuml/cheneer/ChenEerDiagram.java
index 94f447d6f..0decacbef 100644
--- a/src/net/sourceforge/plantuml/cheneer/ChenEerDiagram.java
+++ b/src/net/sourceforge/plantuml/cheneer/ChenEerDiagram.java
@@ -50,10 +50,22 @@ public class ChenEerDiagram extends AbstractEntityDiagram {
 
 	private final Stack<Entity> ownerStack = new Stack<Entity>();
 
+	/**
+	 * Pushes the owner of the following attributes.
+	 *
+	 * @see #peekOwner()
+	 * @param group the entity that owns the following attributes
+	 */
 	public void pushOwner(Entity group) {
 		ownerStack.push(group);
 	}
 
+	/**
+	 * Pops an attribute owner from the stack. See also {@link #peekOwner()}.
+	 * 
+	 * @see #peekOwner()
+	 * @return true if an owner was popped, false if the stack was empty
+	 */
 	public boolean popOwner() {
 		if (ownerStack.isEmpty()) {
 			return false;
@@ -62,6 +74,17 @@ public class ChenEerDiagram extends AbstractEntityDiagram {
 		return true;
 	}
 
+	/**
+	 * Returns the owner of the current attribute.
+	 * 
+	 * <p>
+	 * This is used to link attributes based on their lexical position (how they
+	 * appear in sources) without nesting the entities (like how packages are
+	 * done). It is for this reason that we can't use CucaDiagram.getCurrentGroup,
+	 * as that method nests the entities.
+	 *
+	 * @return the owner of the current attribute, or null if there is no owner
+	 */
 	public Entity peekOwner() {
 		if (ownerStack.isEmpty()) {
 			return null;