From 2caddc3c2a4431aa5d2ffd4e4d1840dbd7c09a64 Mon Sep 17 00:00:00 2001 From: Reinier Zwitserloot Date: Fri, 27 Nov 2009 15:22:43 +0100 Subject: Added documentation for delombok. --- website/features/delombok.html | 72 ++++++++++++++++++++++++++++++++++++++++++ website/features/index.html | 14 ++++++++ 2 files changed, 86 insertions(+) create mode 100644 website/features/delombok.html (limited to 'website') diff --git a/website/features/delombok.html b/website/features/delombok.html new file mode 100644 index 00000000..054516c8 --- /dev/null +++ b/website/features/delombok.html @@ -0,0 +1,72 @@ + + + + + + + + delombok +
+
+
+
Project Lombok
+

delombok

+
+

Overview

+

+ Normally, lombok adds support for all the lombok features directly to your IDE and compiler by plugging into them.
+ However, lombok doesn't cover all tools. For example, lombok cannot plug into javadoc, nor can it plug into the Google Widget Toolkit, both of which + run on java sources. Delombok still allows you to use lombok with these tools by preprocessing your java code into java code with all of lombok's + transformations already applied. +

+ Delombok can of course also help understand what's happening with your source by letting you look at exactly what lombok is doing 'under the hood'. +

+ Delombok's standard mode of operation is that it copies an entire directory into another directory, recursively, skipping class files, and applying + lombok transformations to any java source files it encounters. +

+

Running delombok on the command line

+

+ Delombok is included in lombok.jar. To use it, all you need to run on the command line is: + 

java -jar lombok.jar delombok src -d src-delomboked
+
+ Which will duplicate the contents of the src directory into the src-delomboked directory, which will be created if it + doesn't already exist, but delomboked of course. Delombok on the command line has a few more options; use the --help parameter to see more options. +

+ To let delombok print the transformation result of a single java file directly to standard output, you can use: + 

java -jar lombok.jar delombok -p MyJavaFile.java
+

+

Running delombok in ant

+ lombok.jar includes an ant task which can apply delombok for you. For example, to create javadoc for your project, your build.xml file + would look something like: + 
<target name="javadoc">
+	<taskdef classname="lombok.delombok.ant.DelombokTask" classpath="lib/lombok.jar" name="delombok" />
+	<mkdir dir="build/src-delomboked" />
+	<delombok verbose="true" encoding="UTF-8" to="build/src-delomboked" from="src" />
+	<mkdir dir="build/api" />
+	<javadoc sourcepath="build/src-delomboked" defaultexcludes="yes" destdir="build/api" />
+</target>
+
+ Instead of a from attribute, you can also nest <fileset> nodes. +

Running delombok in maven

+ We don't have a maven plugin for delombok (yet). You'll have to make do with either making maven running an ant script, or letting maven execute + delombok directly as an application. If you'd like to contribute a plugin, do get in touch with us! +

Limitations

+ Delombok tries to preserve your code as much as it can, but comments may move around a little bit, especially comments that are in the middle of + a syntax node. For example, any comments appearing in the middle of a list of method modifiers, such as public /*comment*/ static ... will + move towards the front of the list of modifiers. In practice, any java source parsing tool will not be affected.
+ To keep any changes to your code style to a minimum, delombok just copies a source file directly without changing any of it if the source file contains + no lombok transformations. +
+
+
+ + + diff --git a/website/features/index.html b/website/features/index.html index d7f640ac..9157f503 100644 --- a/website/features/index.html +++ b/website/features/index.html @@ -35,6 +35,20 @@ The documentation above is a lot easier to follow, but if you want to build your own transformations, or you want to add javadoc to lombok.jar in your IDE, you can also check out the javadoc. +

Running Lombok

+

On eclipse

+ Execute lombok.jar (doubleclick it, or run java -jar lombok.jar). Follow instructions. +

On javac (and maven, ant, and other build tools)

+ Include lombok.jar on the classpath as you compile. That's all there is to it!
+ Lombok hosts its own maven repository, so adding lombok to maven is very simple. full instructions are here. +

On GWT (Google Widget Toolkit), javadoc, and other source-based tools

+ Use delombok first, then run javadoc or GWT on the delombok-ed code. +

Running delombok

+
Delombok copies your source files to another directory, replacing all lombok annotations with their desugared form. So, it'll turn @Getter + back into the actual getter. It then removes the annotation. This is useful for all sorts of reasons; you can check out what's happening under the hood, + if the unthinkable happens and you want to stop using lombok, you can easily remove all traces of it in your source, and you can use delombok to preprocess + your source files for source-level tools such as javadoc and GWT. More information about how to run delombok, including instructions for build tools + can be found at the delombok page.
credits | Copyright © 2009 Reinier Zwitserloot and Roel Spilker, licensed under the MIT license.
-- cgit