From 0129a0d18b1bbc126e1125c9053cfe9741c0ea5c Mon Sep 17 00:00:00 2001
From: Pim van der Loos <pimvanderloos@gmail.com>
Date: Mon, 31 May 2021 13:32:05 +0200
Subject: [PATCH] Add website documentation for Locked annotations

---
 .../features/experimental/Locked.html         | 45 +++++++++++++++++++
 .../features/experimental/index.html          |  4 ++
 .../experimental/LockedExample_post.jpage     | 32 +++++++++++++
 .../experimental/LockedExample_pre.jpage      | 20 +++++++++
 4 files changed, 101 insertions(+)
 create mode 100644 website/templates/features/experimental/Locked.html
 create mode 100644 website/usageExamples/experimental/LockedExample_post.jpage
 create mode 100644 website/usageExamples/experimental/LockedExample_pre.jpage

diff --git a/website/templates/features/experimental/Locked.html b/website/templates/features/experimental/Locked.html
new file mode 100644
index 00000000..cd4f599c
--- /dev/null
+++ b/website/templates/features/experimental/Locked.html
@@ -0,0 +1,45 @@
+<#import "../_features.html" as f>
+
+<@f.scaffold title="@Locked" logline="TODO">
+	<@f.history>
+		<p>
+			<code>@Locked</code> was introduced as an experimental feature in lombok v1.18.21.
+		</p>
+	</@f.history>
+
+	<@f.experimental>
+		<ul>
+			<li>
+				New feature – community feedback requested.
+			</li>
+		</ul>
+		Current status: <em>unknown</em>
+	</@f.experimental>
+
+	<@f.overview>
+		<p>
+			@Locked is an alternative to <code>@Synchronized</code> that uses Java locks for more extensive locking operations. The annotation locks on the provided field if one is provided. If no name is provided, the annotation will default to <code>LOCK</code> when used on static methods and to <code>lock</code> for non-static methods. If no field with the specified name exists, one will be generated for you.
+		</p><p>
+			The base <code>@Locked</code> annotation uses a <code>java.util.concurrent.locks.Lock</code> for locking. When required, a <code>java.util.concurrent.locks.ReentrantLock</code> is generated. <br />
+			Additionally, there are the <code>@Locked.Read</code> and <code>@Locked.Write</code> annotations. These use a <code>java.util.concurrent.locks.ReadWriteLock</code>. Methods annotated with <code>@Locked.Write</code> will lock on the write lock and methods annotated with <code>@Locked.Read</code> will lock on the read lock. When required, a <code>java.util.concurrent.locks.ReentrantReadWriteLock</code> is generated.
+		</p>
+	</@f.overview>
+
+	<@f.snippets name="experimental/Locked" />
+
+	<@f.confKeys>
+		<dt>
+			<code>lombok.locked.flagUsage</code> = [<code>warning</code> | <code>error</code>] (default: not set)
+		</dt><dd>
+			Lombok will flag any usage of <code>@Locked</code> as a warning or error if configured.
+		</dd>
+	</@f.confKeys>
+
+	<@f.smallPrint>
+		<p>
+			Because <code>@Locked.Read</code> and <code>@Locked.Write</code> use a different type of lock than <code>@Locked</code>, these annotations cannot be used on the same lock object.<br />
+			The name of the default field of the <code>@Locked</code>, <code>@Locked.Read</code>, and <code>@Locked.Write</code> annotations is the same, so it is not possible to mix the basic <code>@Locked</code> annotation with the other two using the default name.
+		</p>
+	</@f.smallPrint>
+</@f.scaffold>
+
diff --git a/website/templates/features/experimental/index.html b/website/templates/features/experimental/index.html
index a50a4670..12c404bb 100644
--- a/website/templates/features/experimental/index.html
+++ b/website/templates/features/experimental/index.html
@@ -75,6 +75,10 @@
 			<@main.feature title="@StandardException" href="StandardException">
 				Standard.. Exceptional? This is not just an oxymoron, it's convenient!
 			</@main.feature>
+
+			<@main.feature title="@Locked" href="Locked">
+				TODO
+			</@main.feature>
 		</div>
 
 		<@f.confKeys>
diff --git a/website/usageExamples/experimental/LockedExample_post.jpage b/website/usageExamples/experimental/LockedExample_post.jpage
new file mode 100644
index 00000000..86bce0e9
--- /dev/null
+++ b/website/usageExamples/experimental/LockedExample_post.jpage
@@ -0,0 +1,32 @@
+public class LockedExample {
+	private final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
+	private final ReentrantLock baseLock = new ReentrantLock();
+	private int value = 0;
+
+	public int getValue() {
+		this.lock.readLock().lock();
+		try {
+			return value;
+		} finally {
+			this.lock.readLock().unlock();
+		}
+	}
+
+	public void setValue(int newValue) {
+		this.lock.writeLock().lock();
+		try {
+			value = newValue;
+		} finally {
+			this.lock.writeLock().unlock();
+		}
+	}
+
+	public void foo() {
+		this.baseLock.lock();
+		try {
+			System.out.println("bar");
+		} finally {
+			this.baseLock.unlock();
+		}
+	}
+}
diff --git a/website/usageExamples/experimental/LockedExample_pre.jpage b/website/usageExamples/experimental/LockedExample_pre.jpage
new file mode 100644
index 00000000..fdfc7446
--- /dev/null
+++ b/website/usageExamples/experimental/LockedExample_pre.jpage
@@ -0,0 +1,20 @@
+import lombok.experimental.Locked;
+
+public class LockedExample {
+	private int value = 0;
+
+	@Locked.Read
+	public int getValue() {
+		return value;
+	}
+
+	@Locked.Write
+	public void setValue(int newValue) {
+		value = newValue;
+	}
+
+	@Locked("baseLock")
+	public void foo() {
+		System.out.println("bar");
+	}
+}