From 8f295eb31375058b1b988e4c6070213408c8556e Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 12:26:23 +1200 Subject: [PATCH 1/9] Document regex package --- .../plantuml/regex/package-info.java | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 src/net/sourceforge/plantuml/regex/package-info.java diff --git a/src/net/sourceforge/plantuml/regex/package-info.java b/src/net/sourceforge/plantuml/regex/package-info.java new file mode 100644 index 000000000..5d22af6e8 --- /dev/null +++ b/src/net/sourceforge/plantuml/regex/package-info.java @@ -0,0 +1,52 @@ +/* ======================================================================== + * PlantUML : a free UML diagram generator + * ======================================================================== + * + * (C) Copyright 2009-2024, Arnaud Roques + * + * Project Info: https://plantuml.com + * + * If you like this project or if you find it useful, you can support us at: + * + * https://plantuml.com/patreon (only 1$ per month!) + * https://plantuml.com/paypal + * + * This file is part of PlantUML. + * + * PlantUML is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * PlantUML distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public + * License for more details. + * + * You should have received a copy of the GNU General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + * USA. + * + * + * Original Author: Benjamin Davies + * + * + */ + +/** + * Provides classes used to compose regex fragments. + * + *

+ * PlantUML parses text using regular expressions. To aid in readability, these + * are sepecified as trees of {@link RegexComposed} fragments. + * + *

+ * Before a {@link RegexComposed} can be matched, it must first have each + * of its constituent parts concatenated into one large regex string using + * {@link RegexComposed#getFullSlow}. This string is then transformed by + * {@link MyPattern.transform} to replace some macros (e.g. %s + * for whitespace, %q for single quote) and compiled using + * {@link java.util.regex.Pattern#compile}. + */ +package net.sourceforge.plantuml.regex; From 1d1daf492b9dda1a3365571ab7af57bd74c76bf7 Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 12:31:47 +1200 Subject: [PATCH 2/9] Modify wording to match variable names --- src/net/sourceforge/plantuml/regex/package-info.java | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/net/sourceforge/plantuml/regex/package-info.java b/src/net/sourceforge/plantuml/regex/package-info.java index 5d22af6e8..8733d4ee0 100644 --- a/src/net/sourceforge/plantuml/regex/package-info.java +++ b/src/net/sourceforge/plantuml/regex/package-info.java @@ -35,11 +35,12 @@ */ /** - * Provides classes used to compose regex fragments. + * Provides classes used to compose regex partials. * *

* PlantUML parses text using regular expressions. To aid in readability, these - * are sepecified as trees of {@link RegexComposed} fragments. + * are sepecified as trees of {@link RegexComposed} branches and + * {@link RegexLeaf} leaves. * *

* Before a {@link RegexComposed} can be matched, it must first have each From cbab1c333fb76f0d2efc8e35ec7eb86b3ebac4af Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 14:50:34 +1200 Subject: [PATCH 3/9] Document base package --- .../plantuml/SourceFileReader.java | 2 +- .../sourceforge/plantuml/package-info.java | 65 +++++++++++++++++++ .../plantuml/regex/package-info.java | 2 +- 3 files changed, 67 insertions(+), 2 deletions(-) create mode 100644 src/net/sourceforge/plantuml/package-info.java diff --git a/src/net/sourceforge/plantuml/SourceFileReader.java b/src/net/sourceforge/plantuml/SourceFileReader.java index 5213eae3b..4591c6dcf 100644 --- a/src/net/sourceforge/plantuml/SourceFileReader.java +++ b/src/net/sourceforge/plantuml/SourceFileReader.java @@ -147,7 +147,7 @@ public class SourceFileReader extends SourceFileReaderAbstract implements ISourc suggested = SuggestedFile.fromOutputFile(new File(outputDirectory, newName), getFileFormatOption().getFileFormat(), 0); } else { - Log.info("We are going to create files in directory " + dir); + Log.info("We are going to create cypherfiles in directory " + dir); suggested = SuggestedFile.fromOutputFile(new File(dir, getFileName()), getFileFormatOption().getFileFormat(), 0); } diff --git a/src/net/sourceforge/plantuml/package-info.java b/src/net/sourceforge/plantuml/package-info.java new file mode 100644 index 000000000..50d99c8be --- /dev/null +++ b/src/net/sourceforge/plantuml/package-info.java @@ -0,0 +1,65 @@ +/* ======================================================================== + * PlantUML : a free UML diagram generator + * ======================================================================== + * + * (C) Copyright 2009-2024, Arnaud Roques + * + * Project Info: https://plantuml.com + * + * If you like this project or if you find it useful, you can support us at: + * + * https://plantuml.com/patreon (only 1$ per month!) + * https://plantuml.com/paypal + * + * This file is part of PlantUML. + * + * PlantUML is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * PlantUML distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public + * License for more details. + * + * You should have received a copy of the GNU General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + * USA. + * + * + * Original Author: Benjamin Davies + * + * + */ + +/** + * Contains classes for processing PlantUML source files. + * + *

+ * The following is a typical control flow PlantUML: + * + *

+ */ +package net.sourceforge.plantuml; diff --git a/src/net/sourceforge/plantuml/regex/package-info.java b/src/net/sourceforge/plantuml/regex/package-info.java index 8733d4ee0..ee29d767e 100644 --- a/src/net/sourceforge/plantuml/regex/package-info.java +++ b/src/net/sourceforge/plantuml/regex/package-info.java @@ -46,7 +46,7 @@ * Before a {@link RegexComposed} can be matched, it must first have each * of its constituent parts concatenated into one large regex string using * {@link RegexComposed#getFullSlow}. This string is then transformed by - * {@link MyPattern.transform} to replace some macros (e.g. %s + * {@link MyPattern#transform} to replace some macros (e.g. %s * for whitespace, %q for single quote) and compiled using * {@link java.util.regex.Pattern#compile}. */ From ef8879f3b382032cb025147cfaf0548da73c8e2d Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 15:24:25 +1200 Subject: [PATCH 4/9] Document PSystemBuilder --- src/net/sourceforge/plantuml/PSystemBuilder.java | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/src/net/sourceforge/plantuml/PSystemBuilder.java b/src/net/sourceforge/plantuml/PSystemBuilder.java index 0a58f6492..f5b422d36 100644 --- a/src/net/sourceforge/plantuml/PSystemBuilder.java +++ b/src/net/sourceforge/plantuml/PSystemBuilder.java @@ -108,6 +108,13 @@ import net.sourceforge.plantuml.wbs.WBSDiagramFactory; import net.sourceforge.plantuml.wire.WireDiagramFactory; import net.sourceforge.plantuml.yaml.YamlDiagramFactory; +/** + * Builds a diagram from pre-processed PlantUML source. + * + *

+ * Tries each of the factories (enumerated in the static block below) until one + * succeeds. + */ public class PSystemBuilder { // ::remove file when __HAXE__ From 5386b9e7e223666fff48f632a0ec402d3052a27e Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 15:48:49 +1200 Subject: [PATCH 5/9] Document plasma package --- .../sourceforge/plantuml/plasma/PEntry.java | 10 ++++ .../sourceforge/plantuml/plasma/Plasma.java | 5 ++ .../sourceforge/plantuml/plasma/Quark.java | 5 ++ .../plantuml/plasma/package-info.java | 47 +++++++++++++++++++ 4 files changed, 67 insertions(+) create mode 100644 src/net/sourceforge/plantuml/plasma/package-info.java diff --git a/src/net/sourceforge/plantuml/plasma/PEntry.java b/src/net/sourceforge/plantuml/plasma/PEntry.java index 8c84e31ee..1b0e667aa 100644 --- a/src/net/sourceforge/plantuml/plasma/PEntry.java +++ b/src/net/sourceforge/plantuml/plasma/PEntry.java @@ -35,6 +35,16 @@ */ package net.sourceforge.plantuml.plasma; +/** + * Keeps track of the {@link Quark} objects that have a given name. Short for + * {@link Plasma} entry. + * + *

+ * Tracks the first instace created with that name, as well as the number of + * quarks with that name. + * + * @see Plasma#stats + */ class PEntry { // ::remove folder when __HAXE__ diff --git a/src/net/sourceforge/plantuml/plasma/Plasma.java b/src/net/sourceforge/plantuml/plasma/Plasma.java index b592d6221..b5a01931c 100644 --- a/src/net/sourceforge/plantuml/plasma/Plasma.java +++ b/src/net/sourceforge/plantuml/plasma/Plasma.java @@ -42,6 +42,11 @@ import java.util.HashMap; import java.util.List; import java.util.Map; +/** + * A namespace for {@link Quark} objects. + * + * @see net.sourceforge.plantuml.plasma + */ public class Plasma { private String separator = "\u0000"; diff --git a/src/net/sourceforge/plantuml/plasma/Quark.java b/src/net/sourceforge/plantuml/plasma/Quark.java index 9c0b26fc1..b20106ef5 100644 --- a/src/net/sourceforge/plantuml/plasma/Quark.java +++ b/src/net/sourceforge/plantuml/plasma/Quark.java @@ -40,6 +40,11 @@ import java.util.Collections; import java.util.LinkedHashMap; import java.util.Map; +/** + * A named node in the entity graph. + * + * @see net.sourceforge.plantuml.plasma + */ public class Quark { private final Plasma plasma; diff --git a/src/net/sourceforge/plantuml/plasma/package-info.java b/src/net/sourceforge/plantuml/plasma/package-info.java new file mode 100644 index 000000000..a89d3f032 --- /dev/null +++ b/src/net/sourceforge/plantuml/plasma/package-info.java @@ -0,0 +1,47 @@ +/* ======================================================================== + * PlantUML : a free UML diagram generator + * ======================================================================== + * + * (C) Copyright 2009-2024, Arnaud Roques + * + * Project Info: https://plantuml.com + * + * If you like this project or if you find it useful, you can support us at: + * + * https://plantuml.com/patreon (only 1$ per month!) + * https://plantuml.com/paypal + * + * This file is part of PlantUML. + * + * PlantUML is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * PlantUML distributed in the hope that it will be useful, but + * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY + * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public + * License for more details. + * + * You should have received a copy of the GNU General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, + * USA. + * + * + * Original Author: Benjamin Davies + * + * + */ + +/** + * Provides {@link Plasma} and {@link Quark} classes. + * + *

+ * Class diagrams (and other free-form graphs) are represented as a tree of + * enities. The tree structure is represented using {@link Quark} objects, each + * of which corresponds to an {@link net.sourceforge.plantuml.abel.Entity}. The + * quark for an entity can be retrieved using a method on the entity, and + * vice-versa. + */ +package net.sourceforge.plantuml.plasma; From 1a3f5dfd60465f55831c975726ddb763a1e63207 Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 16:15:13 +1200 Subject: [PATCH 6/9] Document "PSystem" implied original meaning --- src/net/sourceforge/plantuml/AbstractPSystem.java | 9 +++++++++ src/net/sourceforge/plantuml/PSystemBuilder.java | 2 ++ src/net/sourceforge/plantuml/plasma/PEntry.java | 2 +- 3 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/net/sourceforge/plantuml/AbstractPSystem.java b/src/net/sourceforge/plantuml/AbstractPSystem.java index bce725466..abebc8b07 100644 --- a/src/net/sourceforge/plantuml/AbstractPSystem.java +++ b/src/net/sourceforge/plantuml/AbstractPSystem.java @@ -67,6 +67,15 @@ import net.sourceforge.plantuml.utils.BlocLines; import net.sourceforge.plantuml.version.License; import net.sourceforge.plantuml.version.Version; +/** + * An abstract class for all diagram classes. + * + *

+ * Short for "{@link net.sourceforge.plantuml.plasma plasma} system", although + * most newer diagram types do not use entities stored in a plasma. + * + * @see PSystemBuilder + */ public abstract class AbstractPSystem implements Diagram { // ::remove file when __HAXE__ diff --git a/src/net/sourceforge/plantuml/PSystemBuilder.java b/src/net/sourceforge/plantuml/PSystemBuilder.java index f5b422d36..b3ebe8d81 100644 --- a/src/net/sourceforge/plantuml/PSystemBuilder.java +++ b/src/net/sourceforge/plantuml/PSystemBuilder.java @@ -114,6 +114,8 @@ import net.sourceforge.plantuml.yaml.YamlDiagramFactory; *

* Tries each of the factories (enumerated in the static block below) until one * succeeds. + * + * @see AbstractPSystem */ public class PSystemBuilder { // ::remove file when __HAXE__ diff --git a/src/net/sourceforge/plantuml/plasma/PEntry.java b/src/net/sourceforge/plantuml/plasma/PEntry.java index 1b0e667aa..9fefcedc7 100644 --- a/src/net/sourceforge/plantuml/plasma/PEntry.java +++ b/src/net/sourceforge/plantuml/plasma/PEntry.java @@ -37,7 +37,7 @@ package net.sourceforge.plantuml.plasma; /** * Keeps track of the {@link Quark} objects that have a given name. Short for - * {@link Plasma} entry. + * "{@link Plasma} entry". * *

* Tracks the first instace created with that name, as well as the number of From fb1ac6d1d2f568117dda38b0b9a9cde012f2feb6 Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 16:22:30 +1200 Subject: [PATCH 7/9] Clean up license attributions --- src/net/sourceforge/plantuml/package-info.java | 2 +- src/net/sourceforge/plantuml/plasma/package-info.java | 2 +- src/net/sourceforge/plantuml/regex/package-info.java | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/net/sourceforge/plantuml/package-info.java b/src/net/sourceforge/plantuml/package-info.java index 50d99c8be..c86934d1c 100644 --- a/src/net/sourceforge/plantuml/package-info.java +++ b/src/net/sourceforge/plantuml/package-info.java @@ -29,7 +29,7 @@ * USA. * * - * Original Author: Benjamin Davies + * Original Author: Arnaud Roques * * */ diff --git a/src/net/sourceforge/plantuml/plasma/package-info.java b/src/net/sourceforge/plantuml/plasma/package-info.java index a89d3f032..b6b3b0c57 100644 --- a/src/net/sourceforge/plantuml/plasma/package-info.java +++ b/src/net/sourceforge/plantuml/plasma/package-info.java @@ -29,7 +29,7 @@ * USA. * * - * Original Author: Benjamin Davies + * Original Author: Arnaud Roques * * */ diff --git a/src/net/sourceforge/plantuml/regex/package-info.java b/src/net/sourceforge/plantuml/regex/package-info.java index ee29d767e..4c0e64e28 100644 --- a/src/net/sourceforge/plantuml/regex/package-info.java +++ b/src/net/sourceforge/plantuml/regex/package-info.java @@ -29,7 +29,7 @@ * USA. * * - * Original Author: Benjamin Davies + * Original Author: Arnaud Roques * * */ From a879026e8cef9cc77fdc48b3895e1eae06e80062 Mon Sep 17 00:00:00 2001 From: Benjamin Davies Date: Sat, 26 Aug 2023 16:24:10 +1200 Subject: [PATCH 8/9] Fix grammatical mistake --- src/net/sourceforge/plantuml/package-info.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/net/sourceforge/plantuml/package-info.java b/src/net/sourceforge/plantuml/package-info.java index c86934d1c..0115df62e 100644 --- a/src/net/sourceforge/plantuml/package-info.java +++ b/src/net/sourceforge/plantuml/package-info.java @@ -38,7 +38,7 @@ * Contains classes for processing PlantUML source files. * *

- * The following is a typical control flow PlantUML: + * The following is a typical control flow for PlantUML: * *