Skip to content

Commit 6704aac

Browse files
nvamelichevnvamelichev
committed
Improve JavaDoc generation, fix minor JavaDoc issues (-missing validation for now)
1 parent ff0529f commit 6704aac

File tree

8 files changed

+117
-38
lines changed

8 files changed

+117
-38
lines changed

‎.github/workflows/build.yaml

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,22 @@ jobs:
4646

4747
- name: Build with Maven
4848
run: mvn $MAVEN_ARGS -Plombok,integration-test -am -pl :yoj-repository-ydb-v2 verify
49+
javadoc-and-source:
50+
name: Validate JavaDoc
51+
runs-on: ubuntu-latest
52+
53+
env:
54+
MAVEN_ARGS: --batch-mode --update-snapshots -Dstyle.color=always
55+
56+
steps:
57+
- uses: actions/checkout@v4
58+
59+
- name: Set up JDK
60+
uses: actions/setup-java@v4
61+
with:
62+
java-version: 17
63+
distribution: 'temurin'
64+
cache: 'maven'
65+
66+
- name: Build with Maven
67+
run: mvn $MAVEN_ARGS -Plombok,javadoc-and-source -DskipTests verify

‎.github/workflows/publish.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ jobs:
7777

7878
- name: Publish package
7979
run: |
80-
mvn $MAVEN_ARGS -Possrh-s01 -Plombok -Dgpg.passphrase=${{ secrets.MAVEN_OSSRH_GPG_PASSWORD }} clean deploy
80+
mvn $MAVEN_ARGS -DyojRelease -DskipTests -Dgpg.passphrase=${{ secrets.MAVEN_OSSRH_GPG_PASSWORD }} clean deploy
8181
env:
8282
MAVEN_USERNAME: ${{ secrets.MAVEN_OSSRH_USERNAME }}
8383
MAVEN_PASSWORD: ${{ secrets.MAVEN_OSSRH_TOKEN }}

‎databind/src/main/java/tech/ydb/yoj/databind/FieldValueType.java

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,6 @@ public enum FieldValueType {
6464
/**
6565
* Binary value: just a stream of uninterpreted bytes.
6666
* Java-side <strong>must</strong> be a {@code byte[]}.
67-
* <p>
6867
*
6968
* @deprecated Support for mapping raw {@code byte[]} will be removed in YOJ 3.0.0.
7069
* Even now, it is strongly recommended to use a {@link ByteArray}: it is properly {@code Comparable}

‎databind/src/main/java/tech/ydb/yoj/databind/schema/Column.java

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,6 @@
6565
* <li>or represented as a single column holding the serialized representation of the field's value
6666
* ({@code flatten=false}).</li>
6767
* </ul>
68-
* </li>
6968
* Defaults to {@code true} (flatten composite fields).<br>
7069
* Changing this parameter for a non-composite field has no effect.
7170
* <p><strong>Tip:</strong> Use the {@link tech.ydb.yoj.databind.converter.ObjectColumn @ObjectColumn} annotation

‎pom.xml

Lines changed: 89 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,8 @@
115115
<!-- build-only dependencies (provided) -->
116116
<lombok.version>1.18.30</lombok.version>
117117
<checkstyle.version>10.12.4</checkstyle.version>
118+
<lombok-maven-plugin.version>1.18.20.0</lombok-maven-plugin.version>
119+
<lombok-maven-plugin.delombok.output>${project.build.directory}/delombok-for-javadoc</lombok-maven-plugin.delombok.output>
118120

119121
<!-- compile dependencies -->
120122
<protobuf.version>3.24.0</protobuf.version>
@@ -158,6 +160,9 @@
158160
<profile>
159161
<activation>
160162
<activeByDefault>true</activeByDefault>
163+
<property>
164+
<name>yojRelease</name>
165+
</property>
161166
</activation>
162167
<id>lombok</id>
163168
<dependencies>
@@ -185,17 +190,72 @@
185190
</profile>
186191
<profile>
187192
<id>integration-test</id>
193+
<activation>
194+
<activeByDefault>false</activeByDefault>
195+
</activation>
188196
<properties>
189197
<test-classes>
190198
**/*IntegrationTest.class,
191199
**/*IntegrationSuite.class,
192200
</test-classes>
193201
</properties>
194202
</profile>
203+
<profile>
204+
<id>javadoc-and-source</id>
205+
<activation>
206+
<activeByDefault>false</activeByDefault>
207+
<property>
208+
<name>yojRelease</name>
209+
</property>
210+
</activation>
211+
<build>
212+
<plugins>
213+
<plugin>
214+
<groupId>org.apache.maven.plugins</groupId>
215+
<artifactId>maven-source-plugin</artifactId>
216+
<executions>
217+
<execution>
218+
<id>attach-sources</id>
219+
<goals>
220+
<goal>jar-no-fork</goal>
221+
</goals>
222+
</execution>
223+
</executions>
224+
</plugin>
225+
<plugin>
226+
<groupId>org.projectlombok</groupId>
227+
<artifactId>lombok-maven-plugin</artifactId>
228+
<executions>
229+
<execution>
230+
<id>delombok-for-javadoc</id>
231+
<goals>
232+
<goal>delombok</goal>
233+
</goals>
234+
</execution>
235+
</executions>
236+
</plugin>
237+
<plugin>
238+
<groupId>org.apache.maven.plugins</groupId>
239+
<artifactId>maven-javadoc-plugin</artifactId>
240+
<executions>
241+
<execution>
242+
<id>attach-javadocs</id>
243+
<goals>
244+
<goal>jar</goal>
245+
</goals>
246+
</execution>
247+
</executions>
248+
</plugin>
249+
</plugins>
250+
</build>
251+
</profile>
195252
<profile>
196253
<id>ossrh-s01</id>
197254
<activation>
198255
<activeByDefault>false</activeByDefault>
256+
<property>
257+
<name>yojRelease</name>
258+
</property>
199259
</activation>
200260

201261
<build>
@@ -371,14 +431,41 @@
371431
<artifactId>maven-source-plugin</artifactId>
372432
<version>${maven-source-plugin.version}</version>
373433
</plugin>
434+
<plugin>
435+
<groupId>org.projectlombok</groupId>
436+
<artifactId>lombok-maven-plugin</artifactId>
437+
<version>${lombok-maven-plugin.version}</version>
438+
<executions>
439+
<execution>
440+
<id>delombok-for-javadoc</id>
441+
<phase>generate-sources</phase>
442+
<goals>
443+
<goal>delombok</goal>
444+
</goals>
445+
<configuration>
446+
<sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
447+
<outputDirectory>${lombok-maven-plugin.delombok.output}</outputDirectory>
448+
<addOutputDirectory>false</addOutputDirectory>
449+
</configuration>
450+
</execution>
451+
</executions>
452+
<dependencies>
453+
<dependency>
454+
<groupId>org.projectlombok</groupId>
455+
<artifactId>lombok</artifactId>
456+
<version>${lombok.version}</version>
457+
</dependency>
458+
</dependencies>
459+
</plugin>
374460
<plugin>
375461
<groupId>org.apache.maven.plugins</groupId>
376462
<artifactId>maven-javadoc-plugin</artifactId>
377463
<version>${maven-javadoc-plugin.version}</version>
378464
<configuration>
379465
<source>${java.version}</source>
380-
<!-- FIXME(entropia@): fix malformed HTML and re-enable doclint -->
381-
<doclint>none</doclint>
466+
<sourcepath>${lombok-maven-plugin.delombok.output}</sourcepath>
467+
<!-- TODO(nvamelichev@): Enable 'missing' validation and fix the docs -->
468+
<doclint>all,-missing</doclint>
382469
</configuration>
383470
</plugin>
384471
<plugin>
@@ -397,30 +484,6 @@
397484
<groupId>org.apache.maven.plugins</groupId>
398485
<artifactId>maven-surefire-plugin</artifactId>
399486
</plugin>
400-
<plugin>
401-
<groupId>org.apache.maven.plugins</groupId>
402-
<artifactId>maven-source-plugin</artifactId>
403-
<executions>
404-
<execution>
405-
<id>attach-sources</id>
406-
<goals>
407-
<goal>jar-no-fork</goal>
408-
</goals>
409-
</execution>
410-
</executions>
411-
</plugin>
412-
<plugin>
413-
<groupId>org.apache.maven.plugins</groupId>
414-
<artifactId>maven-javadoc-plugin</artifactId>
415-
<executions>
416-
<execution>
417-
<id>attach-javadocs</id>
418-
<goals>
419-
<goal>jar</goal>
420-
</goals>
421-
</execution>
422-
</executions>
423-
</plugin>
424487
<plugin>
425488
<groupId>org.apache.maven.plugins</groupId>
426489
<artifactId>maven-checkstyle-plugin</artifactId>

‎repository-ydb-v2/src/main/java/tech/ydb/yoj/repository/ydb/YdbSpliterator.java

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,9 @@
2929
* It's possible to supply values from different threads, but supplier threads must not call {@code onNext()} concurrently.
3030
* This Spliterator should be explicitly closed by the {@code close()} method for finish work in YDB session; when the stream returned by
3131
* {@code readTable()} is used inside a YOJ transaction, {@code close()} will be called automatically at transaction end (both commit and rollback).
32-
* <p>To use the new implementation, set {@link tech.ydb.yoj.repository.db.readtable.ReadTableParams.ReadTableParamsBuilder#useNewSpliterator(boolean)
33-
* ReadTableParams<...>.builder().<...>.useNewSpliterator(true)}.
32+
* <p>To use the new implementation, set
33+
* {@link tech.ydb.yoj.repository.db.readtable.ReadTableParams.ReadTableParamsBuilder#useNewSpliterator(boolean)
34+
* ReadTableParams&lt;YourEntity.Id&gt;.builder().useNewSpliterator(true).build()}.
3435
* <p>Note that using the new implementation currently has a negative performance impact, for more information refer to
3536
* <a href="https://github.com/ydb-platform/yoj-project/issues/42">GitHub Issue #42</a>.
3637
*/

‎repository/src/main/java/tech/ydb/yoj/repository/db/RepositoryTransaction.java

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,24 @@
44
import tech.ydb.yoj.repository.db.exception.OptimisticLockException;
55

66
/**
7-
* A DB transaction. Each instance <i><must</i> be closed with {@link #commit()} or {@link #rollback} methods (exactly
8-
* one call to either method) lest your transaction stays active on the DB server.
7+
* A DB transaction. Each instance <strong>must</strong> be closed with {@link #commit()} or {@link #rollback} methods
8+
* (exactly one call to either method) lest your transaction stays active on the DB server.
99
*/
1010
public interface RepositoryTransaction {
1111
<T extends Entity<T>> Table<T> table(Class<T> c);
1212

1313
<T extends Entity<T>> Table<T> table(TableDescriptor<T> tableDescriptor);
1414

1515
/**
16-
* Commits the transaction or throws exception. Note that this method is not expected to be called, if the last
16+
* Commits the transaction or throws exception. Note that this method is not expected to be called if the last
1717
* transaction statement has thrown an exception, because it means that transaction didn't 'execute normally'.
1818
*
1919
* @throws OptimisticLockException if the transaction's optimistic attempt has failed and it ought to be started over
2020
*/
2121
void commit() throws OptimisticLockException;
2222

2323
/**
24-
* Rollbacks that transaction. This method <i>must</i> be called in the end unless {@link #commit()} method was chosen for calling.
24+
* Rollbacks that transaction. This method <strong>must</strong> be called in the end unless {@link #commit()} method was chosen for calling.
2525
* If this method throws an exception, the transaction consistency is not confirmed and none of its results can be used
2626
* (you may very well be inside a catch clause right now, having caught an exception from your transaction and calling the rollback method
2727
* on this occasion; even so, your exception is a <i>result</i> of your transaction and it must be disregarded, because the

‎repository/src/main/java/tech/ydb/yoj/repository/db/projection/ProjectionMappings.java

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,9 +58,7 @@ public static <P extends Entity<P>, T extends Entity<T>> Map<String, String> len
5858
* Creates a one-to-one mapping from entity fields to entity projection ID fields, assuming that the projection ID
5959
* contains fields with the same name as in the main entity and <em>at most one</em> field for the main entity ID
6060
* (with any name).
61-
* </ul>
62-
* <p>
63-
* <em>E.g.</em>, the following entity-projection pair qualifies: <blockquote><pre>
61+
* <p><em>E.g.</em>, the following entity-projection pair qualifies: <blockquote><pre>
6462
* &#64;Value class MyEntity implements Entity&lt;MyEntity> {
6563
* Id id;
6664
* String field;

0 commit comments

Comments
 (0)