Merge pull request #1520 from Benjamin-Davies/docs

Add some documentation

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.
+ * 
+ * <p>
+ * 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__
 

src/net/sourceforge/plantuml/PSystemBuilder.java

@@ -108,6 +108,15 @@ 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.
+ *
+ * <p>
+ * Tries each of the factories (enumerated in the static block below) until one
+ * succeeds.
+ *
+ * @see AbstractPSystem
+ */
 public class PSystemBuilder {
 	// ::remove file when __HAXE__
 

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:  Arnaud Roques
+ * 
+ *
+ */
+
+/**
+ * Contains classes for processing PlantUML source files.
+ *
+ * <p>
+ * The following is a typical control flow for PlantUML:
+ *
+ * <ul>
+ * <li>
+ * Arguments are parsed ({@link Run} constructs {@link Option}),
+ * </li>
+ * <li>
+ * Files are read ({@link Run} constructs {@link SourceFileReaderAbstract}),
+ * </li>
+ * <li>
+ * Files are split into blocks ({@link SourceFileReaderAbstract} constructs
+ * {@link BlockUmlBuilder}),
+ * <li>
+ * Blocks are pre-processed ({@link BlockUml} uses
+ * {@link net.sourceforge.plantuml.tim.TimLoader}),
+ * </li>
+ * <li>
+ * Blocks are processed and the output images saved ({@link Run} calls
+ * {@link SourceFileReaderAbstract#getGeneratedImages()} which calls
+ * {@link BlockUml#getDiagram()} which uses
+ * {@link PSystemBuilder}),
+ * </li>
+ * </ul>
+ */
+package net.sourceforge.plantuml;

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".
+ * 
+ * <p>
+ * Tracks the first instace created with that name, as well as the number of
+ * quarks with that name.
+ *
+ * @see Plasma#stats
+ */
 class PEntry<DATA> {
     // ::remove folder when __HAXE__
 

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<DATA> {
 
 	private String separator = "\u0000";

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<DATA> {
 
 	private final Plasma<DATA> plasma;

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:  Arnaud Roques
+ * 
+ *
+ */
+
+/**
+ * Provides {@link Plasma} and {@link Quark} classes.
+ * 
+ * <p>
+ * 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;

src/net/sourceforge/plantuml/regex/package-info.java

@@ -0,0 +1,53 @@
+/* ========================================================================
+ * 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:  Arnaud Roques
+ * 
+ *
+ */
+
+/**
+ * Provides classes used to compose regex partials.
+ * 
+ * <p>
+ * PlantUML parses text using regular expressions. To aid in readability, these
+ * are sepecified as trees of {@link RegexComposed} branches and
+ * {@link RegexLeaf} leaves.
+ * 
+ * <p>
+ * 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;