[OO] Javadoc & readibility improvements (#12216)

* Add `@implSpec` tags, clean docs * Fix variable name, link * Fix more javadoc * Add `controlsfx.skin` module export * Fix rendering list of requirements * Rename variables (bibliography) * Fix method name in comment
JabRef · Dec 17, 2024 · 006bbd0 · 006bbd0
1 parent 7c342c8
commit 006bbd0
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 30 deletions.
diff --git a/build.gradle b/build.gradle
@@ -594,7 +594,8 @@ javadoc {
         version = false
         author = false
         addMultilineStringsOption("-add-exports").setValue([
-            'javafx.controls/com.sun.javafx.scene.control=org.jabref'
+            'javafx.controls/com.sun.javafx.scene.control=org.jabref',
+            'org.controlsfx.controls/impl.org.controlsfx.skin=org.jabref'
         ])
     }
 }

diff --git a/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLCitationOOAdapter.java b/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLCitationOOAdapter.java
@@ -54,14 +54,14 @@ public void insertCitation(XTextCursor cursor, CitationStyle selectedStyle, List
         String style = selectedStyle.getSource();
         boolean isAlphanumeric = isAlphanumericStyle(selectedStyle);
 
-        String inTextCitation;
+        String citation;
         if (isAlphanumeric) {
-            inTextCitation = CSLFormatUtils.generateAlphanumericCitation(entries, bibDatabaseContext);
+            citation = CSLFormatUtils.generateAlphanumericCitation(entries, bibDatabaseContext);
         } else {
-            inTextCitation = CitationStyleGenerator.generateCitation(entries, style, CSLFormatUtils.OUTPUT_FORMAT, bibDatabaseContext, bibEntryTypesManager).getText();
+            citation = CitationStyleGenerator.generateCitation(entries, style, CSLFormatUtils.OUTPUT_FORMAT, bibDatabaseContext, bibEntryTypesManager).getText();
         }
 
-        String formattedCitation = CSLFormatUtils.transformHTML(inTextCitation);
+        String formattedCitation = CSLFormatUtils.transformHTML(citation);
 
         if (selectedStyle.isNumericStyle()) {
             formattedCitation = updateSingleOrMultipleCitationNumbers(formattedCitation, entries);
@@ -75,7 +75,7 @@ public void insertCitation(XTextCursor cursor, CitationStyle selectedStyle, List
      * Inserts in-text citations for a group of entries.
      * Comparable to LaTeX's \citet command.
      *
-     * @implNote Very similar to the {@link #insertCitation(XTextCursor, CitationStyle, List, BibDatabaseContext, BibEntryTypesManager)} method.insertInText method
+     * @implNote Very similar to the {@link #insertCitation(XTextCursor, CitationStyle, List, BibDatabaseContext, BibEntryTypesManager) insertCitation} method.
      */
     public void insertInTextCitation(XTextCursor cursor, CitationStyle selectedStyle, List<BibEntry> entries, BibDatabaseContext bibDatabaseContext, BibEntryTypesManager bibEntryTypesManager)
             throws IOException, CreationException, Exception {
@@ -152,22 +152,22 @@ public void insertBibliography(XTextCursor cursor, CitationStyle selectedStyle,
             entries.sort(Comparator.comparingInt(entry -> markManager.getCitationNumber(entry.getCitationKey().orElse(""))));
 
             for (BibEntry entry : entries) {
-                String citation = CitationStyleGenerator.generateBibliography(List.of(entry), style, CSLFormatUtils.OUTPUT_FORMAT, bibDatabaseContext, bibEntryTypesManager).getFirst();
+                String bibliographyEntry = CitationStyleGenerator.generateBibliography(List.of(entry), style, CSLFormatUtils.OUTPUT_FORMAT, bibDatabaseContext, bibEntryTypesManager).getFirst();
                 String citationKey = entry.getCitationKey().orElse("");
                 int currentNumber = markManager.getCitationNumber(citationKey);
 
-                String formattedCitation = CSLFormatUtils.updateSingleBibliographyNumber(CSLFormatUtils.transformHTML(citation), currentNumber);
-                OOText ooText = OOFormat.setLocaleNone(OOText.fromString(formattedCitation));
+                String formattedBibliographyEntry = CSLFormatUtils.updateSingleBibliographyNumber(CSLFormatUtils.transformHTML(bibliographyEntry), currentNumber);
+                OOText ooText = OOFormat.setLocaleNone(OOText.fromString(formattedBibliographyEntry));
 
                 OOTextIntoOO.write(document, cursor, ooText);
             }
         } else {
             // Ordering will be according to citeproc item data provider (default)
-            List<String> citations = CitationStyleGenerator.generateBibliography(entries, style, CSLFormatUtils.OUTPUT_FORMAT, bibDatabaseContext, bibEntryTypesManager);
+            List<String> bibliographyEntries = CitationStyleGenerator.generateBibliography(entries, style, CSLFormatUtils.OUTPUT_FORMAT, bibDatabaseContext, bibEntryTypesManager);
 
-            for (String citation : citations) {
-                String formattedCitation = CSLFormatUtils.transformHTML(citation);
-                OOText ooText = OOFormat.setLocaleNone(OOText.fromString(formattedCitation));
+            for (String bibliographyEntry : bibliographyEntries) {
+                String formattedBibliographyEntry = CSLFormatUtils.transformHTML(bibliographyEntry);
+                OOText ooText = OOFormat.setLocaleNone(OOText.fromString(formattedBibliographyEntry));
                 OOTextIntoOO.write(document, cursor, ooText);
             }
         }

diff --git a/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLFormatUtils.java b/src/main/java/org/jabref/logic/openoffice/oocsltext/CSLFormatUtils.java
@@ -36,7 +36,7 @@ public class CSLFormatUtils {
 
     /**
      * Transforms provided HTML into a format that can be fully parsed and inserted into an OO document.
-     * Context: The HTML produced by {@link org.jabref.logic.citationstyle.CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} or {@link org.jabref.logic.citationstyle.CitationStyleGenerator#generateCitation(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateCitation} is not directly (completely) parsable by by {@link OOTextIntoOO#write(XTextDocument, XTextCursor, OOText) write}.
+     * Context: The HTML produced by {@link org.jabref.logic.citationstyle.CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} or {@link org.jabref.logic.citationstyle.CitationStyleGenerator#generateCitation(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateCitation} is not directly (completely) parsable by {@link OOTextIntoOO#write(XTextDocument, XTextCursor, OOText) write}.
      * For more details, read the documentation for the {@link OOTextIntoOO} class.
      * <a href="https://devdocs.jabref.org/code-howtos/openoffice/code-reorganization.html">Additional Information</a>.
      *
@@ -122,7 +122,7 @@ public static String generateAlphanumericCitation(List<BibEntry> entries, BibDat
 
     /**
      * Method to update citation number of a bibliographic entry (to be inserted in the list of references).
-     * By default, citeproc-java ({@link org.jabref.logic.citationstyle.CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} always starts the numbering of a list of citations with "1".
+     * By default, citeproc-java ({@link org.jabref.logic.citationstyle.CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography}) always starts the numbering of a list of references with "1".
      * If a citation doesn't correspond to the first cited entry, the number should be changed to the appropriate current citation number.
      * The numbers should be globally unique. If an entry has been cited before, the older citation number corresponding to it should be reused.
      * The number can be enclosed in different formats, such as "1", "1.", "1)", "(1)" or "[1]".

diff --git a/src/test/java/org/jabref/logic/openoffice/oocsltext/CSLFormatUtilsTest.java b/src/test/java/org/jabref/logic/openoffice/oocsltext/CSLFormatUtilsTest.java
@@ -142,9 +142,8 @@ static Stream<Arguments> ooHTMLTransformFromRawHTML() {
 
     /**
      * Test to check correct transformation of raw CSL bibliography generated by citeproc-java methods into OO-ready text.
-     * <p>
-     * <b>Precondition:</b> This test assumes that {@link CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} works as expected.
-     * </p>
+     *
+     * @implSpec Assumes that {@link CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} works as expected.
      */
     @ParameterizedTest
     @MethodSource
@@ -254,9 +253,8 @@ static Stream<Arguments> ooHTMLTransformFromRawBibliography() {
 
     /**
      * Test to check correct transformation of raw CSL citation with a single entry generated by citeproc-java methods into OO-ready text.
-     * <p>
-     * <b>Precondition:</b> This test assumes that {@link CitationStyleGenerator#generateCitation(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateCitation} works as expected.
-     * </p>
+     *
+     * @implSpec Assumes that {@link CitationStyleGenerator#generateCitation(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateCitation} works as expected.
      */
     @ParameterizedTest
     @MethodSource
@@ -356,9 +354,8 @@ static Stream<Arguments> ooHTMLTransformFromCitationWithSingleEntry() {
 
     /**
      * Test to check correct transformation of raw CSL citations with multiple entries generated by citeproc-java methods into OO-ready text.
-     * <p>
-     * <b>Precondition:</b> This test assumes that {@link CitationStyleGenerator#generateCitation(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateCitation} works as expected.
-     * </p>
+     *
+     * @implSpec Assumes that {@link CitationStyleGenerator#generateCitation(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateCitation} works as expected.
      */
     @ParameterizedTest
     @MethodSource
@@ -482,10 +479,13 @@ static Stream<Arguments> ooHTMLTransformFromCitationWithMultipleEntries() {
      * Test for modifying the number (index) of a numeric citation.
      * The numeric index should change to the provided "current number".
      * The rest of the citation should stay as it is (other numbers in the body shouldn't be affected).
-     * <p>
-     * <b>Precondition 1:</b> This test assumes that {@link CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} works as expected.<br>
-     * <b>Precondition 2:</b> This test assumes that the method {@link CSLFormatUtils#transformHTML(String) transformHTML} works as expected.<br>
-     * <b>Precondition 3:</b> Run this test ONLY on numeric Citation Styles.</p>
+     *
+     * @implSpec
+     * <ol>
+     * <li>Assumes that {@link CitationStyleGenerator#generateBibliography(List, String, CitationStyleOutputFormat, BibDatabaseContext, BibEntryTypesManager) generateBibliography} works as expected.</li>
+     * <li>Assumes that the method {@link CSLFormatUtils#transformHTML(String) transformHTML} works as expected.</li>
+     * <li>Run this test ONLY on numeric Citation Styles.</li>
+     * </ol>
      */
     @ParameterizedTest
     @MethodSource
@@ -593,8 +593,8 @@ private static Stream<Arguments> ChangeToInText() {
 
     /**
      * Test for proper generation of alphanumeric citations (currently supported: DIN 1505-2).
-     * <p>
-     * <b>Precondition:</b> This test assumes that the method {@link org.jabref.logic.citationkeypattern.BracketedPattern#authorsAlpha authorsAlpha} works as expected.</p>
+     *
+     * @implSpec Assumes that the method {@link org.jabref.logic.citationkeypattern.BracketedPattern#authorsAlpha authorsAlpha} works as expected.</p>
      */
     @ParameterizedTest
     @MethodSource