Skip to content

Commit 541b7d7

Browse files
authored
Enforce one-sentence-per-line rule in adoc (spring-attic#1345)
Bring existing ascii docs into compliance with one-sentence-per-line adoc best practice https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line
1 parent 1d96c8c commit 541b7d7

File tree

29 files changed

+209
-276
lines changed

29 files changed

+209
-276
lines changed

CODE_OF_CONDUCT.adoc

+11-31
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,7 @@
22

33
== Our Pledge
44

5-
In the interest of fostering an open and welcoming environment, we as
6-
contributors and maintainers pledge to making participation in our project and
7-
our community a harassment-free experience for everyone, regardless of age, body
8-
size, disability, ethnicity, gender identity and expression, level of experience,
9-
nationality, personal appearance, race, religion, or sexual identity and
10-
orientation.
5+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
116

127
== Our Standards
138

@@ -33,40 +28,25 @@ Examples of unacceptable behavior by participants include:
3328

3429
== Our Responsibilities
3530

36-
Project maintainers are responsible for clarifying the standards of acceptable
37-
behavior and are expected to take appropriate and fair corrective action in
38-
response to any instances of unacceptable behavior.
31+
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
3932

40-
Project maintainers have the right and responsibility to remove, edit, or
41-
reject comments, commits, code, wiki edits, issues, and other contributions
42-
that are not aligned to this Code of Conduct, or to ban temporarily or
43-
permanently any contributor for other behaviors that they deem inappropriate,
44-
threatening, offensive, or harmful.
33+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
4534

4635
== Scope
4736

48-
This Code of Conduct applies both within project spaces and in public spaces
49-
when an individual is representing the project or its community. Examples of
50-
representing a project or community include using an official project e-mail
51-
address, posting via an official social media account, or acting as an appointed
52-
representative at an online or offline event. Representation of a project may be
53-
further defined and clarified by project maintainers.
37+
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.
38+
Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
39+
Representation of a project may be further defined and clarified by project maintainers.
5440

5541
== Enforcement
5642

57-
Instances of abusive, harassing, or otherwise unacceptable behavior may be
58-
reported by contacting the project team. All
59-
complaints will be reviewed and investigated and will result in a response that
60-
is deemed necessary and appropriate to the circumstances. The project team is
61-
obligated to maintain confidentiality with regard to the reporter of an incident.
43+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team.
44+
All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
45+
The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
6246
Further details of specific enforcement policies may be posted separately.
6347

64-
Project maintainers who do not follow or enforce the Code of Conduct in good
65-
faith may face temporary or permanent repercussions as determined by other
66-
members of the project's leadership.
48+
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
6749

6850
== Attribution
6951

70-
This Code of Conduct is adapted from the https://www.contributor-covenant.org[Contributor
71-
Covenant], version 1.4,
72-
available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
52+
This Code of Conduct is adapted from the https://www.contributor-covenant.org[Contributor Covenant], version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

CONTRIBUTING.adoc

+11-18
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,24 @@
11
= Code formatting guidelines
22

3-
The directory src/eclipse has two files for use with code formatting, `eclipse-code-formatter.xml`
4-
for the majority of the code formatting rules and `eclipse.importorder` to order the import
5-
statements.
3+
The directory src/eclipse has two files for use with code formatting, `eclipse-code-formatter.xml` for the majority of the code formatting rules and `eclipse.importorder` to order the import statements.
64

75
== Eclipse
86
Import these files by navigating `Windows -> Preferences` and then the menu items
97
`Preferences > Java > Code Style > Formatter` and `Preferences > Java > Code Style >
108
Organize Imports` respectively.
119

1210
== IntelliJ IDEA
13-
Install the plugin `Eclipse Code Formatter`. You can find it by searching in "Browse Repositories",
14-
under `Settings > Plugins` within IDEA (Once installed, you will need to reboot IDEA for it to take
15-
effect).
11+
Install the plugin `Eclipse Code Formatter`.
12+
You can find it by searching in "Browse Repositories", under `Settings > Plugins` within IDEA (Once installed, you will need to reboot IDEA for it to take effect).
1613

17-
Then navigate to `Settings > Other Settings` (this might be under `Preferences` on Mac) and select
18-
the Eclipse Code Formatter.
19-
Select the `eclipse-code-formatter.xml` file for the field `Eclipse Java Formatter config file` and
20-
the file `eclipse.importorder` for the field `Import order`.
21-
Enable the `Eclipse code formatter` by clicking `Use the Eclipse code formatter` radio button at the
22-
top of the page, then click the *OK* button.
14+
Then navigate to `Settings > Other Settings` (this might be under `Preferences` on Mac) and select the Eclipse Code Formatter.
15+
Select the `eclipse-code-formatter.xml` file for the field `Eclipse Java Formatter config file` and the file `eclipse.importorder` for the field `Import order`.
16+
Enable the `Eclipse code formatter` by clicking `Use the Eclipse code formatter` radio button at the top of the page, then click the *OK* button.
2317

24-
* NOTE: If you configure the `Eclipse Code Formatter` from `File > Other Settings > Default
25-
Settings`, it will set this policy across all of your IDEA projects.
18+
* NOTE: If you configure the `Eclipse Code Formatter` from `File > Other Settings > Default Settings`, it will set this policy across all of your IDEA projects.
2619

27-
* IDEA's "Optimize imports on the fly" option turned on interferes with the Eclipse code formatter
28-
import optimization. Consider disabling the option if optimization does not yield the expected
29-
results.
20+
* IDEA's "Optimize imports on the fly" option turned on interferes with the Eclipse code formatter import optimization.
21+
Consider disabling the option if optimization does not yield the expected results.
3022

3123
= Contributing a patch
3224

@@ -45,4 +37,5 @@ Guide]
4537

4638
6. Ensure your code has an appropriate set of unit tests which all pass
4739

48-
7. Submit a pull request. It will be approved and merged by a committer
40+
7. Submit a pull request.
41+
It will be approved and merged by a committer

README.adoc

+1-1
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Our starters handle the object instantiation and configuration logic so you don'
8585
Every starter depends on the GCP starter to provide critical bits of configuration, like the GCP project ID or OAuth2 credentials location.
8686
You can configure these as properties in, for example, a properties file:
8787

88-
[source, yaml]
88+
[source]
8989
----
9090
spring.cloud.gcp.project-id=[YOUR_GCP_PROJECT_ID]
9191
spring.cloud.gcp.credentials.location=file:[LOCAL_PRIVATE_KEY_FILE]

docs/src/main/asciidoc/config.adoc

+3-1
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ NOTE: Core properties, as described in <<spring-cloud-gcp-core,Spring Cloud GCP
5353
In other words, if `spring.application.name` is `myapp` and `spring.profiles.active` is `prod`, the configuration should be called `myapp_prod`.
5454
+
5555
In order to do that, you should have the https://cloud.google.com/sdk/[Google Cloud SDK] installed, own a Google Cloud Project and run the following command:
56-
+
56+
[source]
5757
----
5858
gcloud init # if this is your first Google Cloud SDK run.
5959
gcloud beta runtime-config configs create myapp_prod
@@ -62,12 +62,14 @@ gcloud beta runtime-config configs variables set myapp.queue-size 25 --config-na
6262

6363
2. Configure your `bootstrap.properties` file with your application's configuration data:
6464
+
65+
[source]
6566
----
6667
spring.application.name=myapp
6768
spring.profiles.active=prod
6869
----
6970
3. Add the `@ConfigurationProperties` annotation to a Spring-managed bean:
7071
+
72+
[source]
7173
----
7274
@Component
7375
@ConfigurationProperties("myapp")

docs/src/main/asciidoc/core.adoc

+3-3
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ It uses the `spring.cloud.gcp.credentials.location` property to locate the OAuth
6868
Keep in mind this property is a Spring Resource, so the credentials file can be obtained from a number of https://docs.spring.io/spring/docs/current/spring-framework-reference/html/resources.html#resources-implementations[different locations] such as the file system, classpath, URL, etc.
6969
The next example specifies the credentials location property in the file system.
7070

71-
[source,yaml]
71+
[source]
7272
----
7373
spring.cloud.gcp.credentials.location=file:/usr/local/key.json
7474
----
@@ -109,14 +109,14 @@ To do that, specify a comma-delimited list of https://developers.google.com/iden
109109

110110
`spring.cloud.gcp.credentials.scopes` is a comma-delimited list of https://developers.google.com/identity/protocols/googlescopes[Google OAuth2 scopes] for Google Cloud Platform services that the credentials returned by the provided `CredentialsProvider` support.
111111

112-
[source,yaml]
112+
[source]
113113
----
114114
spring.cloud.gcp.credentials.scopes=https://www.googleapis.com/auth/pubsub,https://www.googleapis.com/auth/sqlservice.admin
115115
----
116116

117117
You can also use `DEFAULT_SCOPES` placeholder as a scope to represent the starters default scopes, and append the additional scopes you need to add.
118118

119-
[source,yaml]
119+
[source]
120120
----
121121
spring.cloud.gcp.credentials.scopes=DEFAULT_SCOPES,https://www.googleapis.com/auth/cloud-vision
122122
----

docs/src/main/asciidoc/datastore.adoc

+26-24
Original file line numberDiff line numberDiff line change
@@ -64,8 +64,7 @@ The following configuration options are available:
6464
|===
6565
| Name | Description | Required | Default value
6666
| `spring.cloud.gcp.datastore.enabled` | Enables the Cloud Datastore client | No | `true`
67-
| `spring.cloud.gcp.datastore.project-id` | GCP project ID where the Google Cloud Datastore API
68-
is hosted, if different from the one in the <<spring-cloud-gcp-core,Spring Cloud GCP Core Module>>
67+
| `spring.cloud.gcp.datastore.project-id` | GCP project ID where the Google Cloud Datastore API is hosted, if different from the one in the <<spring-cloud-gcp-core,Spring Cloud GCP Core Module>>
6968
| No |
7069
| `spring.cloud.gcp.datastore.credentials.location` | OAuth2 credentials for authenticating with the
7170
Google Cloud Datastore API, if different from the ones in the
@@ -116,7 +115,8 @@ public class Trader {
116115
}
117116
----
118117

119-
Spring Data Cloud Datastore will ignore any property annotated with `@Transient`. These properties will not be written to or read from Cloud Datastore.
118+
Spring Data Cloud Datastore will ignore any property annotated with `@Transient`.
119+
These properties will not be written to or read from Cloud Datastore.
120120

121121
==== Constructors
122122

@@ -220,13 +220,11 @@ In addition, all types that can be converted to the ones listed in the table by
220220

221221
Custom converters can be used extending the type support for user defined types.
222222

223-
. Converters need to implement the `org.springframework.core.convert.converter.Converter` interface in
224-
both directions.
223+
. Converters need to implement the `org.springframework.core.convert.converter.Converter` interface in both directions.
225224

226225
. The user defined type needs to be mapped to one of the basic types supported by Cloud Datastore.
227226

228-
. An instance of both Converters (read and write) needs to be passed to the `DatastoreCustomConversions` constructor,
229-
which then has to be made available as a `@Bean` for `DatastoreCustomConversions`.
227+
. An instance of both Converters (read and write) needs to be passed to the `DatastoreCustomConversions` constructor, which then has to be made available as a `@Bean` for `DatastoreCustomConversions`.
230228

231229
For example:
232230

@@ -306,17 +304,15 @@ Elements are converted to Cloud Datastore supported types individually. `byte[]`
306304

307305
==== Custom Converter for collections
308306
Users can provide converters from `List<?>` to the custom collection type.
309-
Only read converter is necessary, the Collection API is used on the write side to convert a collection to
310-
the internal list type.
307+
Only read converter is necessary, the Collection API is used on the write side to convert a collection to the internal list type.
311308

312309
Collection converters need to implement the `org.springframework.core.convert.converter.Converter` interface.
313310

314311

315312
Example:
316313

317314
Let's improve the Singer class from the previous example.
318-
Instead of a field of type `Album`,
319-
we would like to have a field of type `ImmutableSet<Album>`:
315+
Instead of a field of type `Album`, we would like to have a field of type `ImmutableSet<Album>`:
320316

321317
[source, java]
322318
----
@@ -703,7 +699,8 @@ In the example above the first two reads utilize keys, while the third is execut
703699

704700
===== Indexes
705701

706-
By default, all fields are indexed. To disable indexing on a particular field, `@Unindexed` annotation can be used.
702+
By default, all fields are indexed.
703+
To disable indexing on a particular field, `@Unindexed` annotation can be used.
707704

708705
Example:
709706
[source, java]
@@ -763,15 +760,17 @@ DatastoreOperations myDatastoreOperations;
763760
public String doWorkInsideTransaction() {
764761
return myDatastoreOperations.performTransaction(
765762
transactionDatastoreOperations -> {
766-
// work with transactionDatastoreOperations here. It is also a DatastoreOperations object.
763+
// Work with transactionDatastoreOperations here.
764+
// It is also a DatastoreOperations object.
767765
768766
return "transaction completed";
769767
}
770768
);
771769
}
772770
----
773771

774-
The `performTransaction` method accepts a `Function` that is provided an instance of a `DatastoreOperations` object. The final returned value and type of the function is determined by the user.
772+
The `performTransaction` method accepts a `Function` that is provided an instance of a `DatastoreOperations` object.
773+
The final returned value and type of the function is determined by the user.
775774
You can use this object just as you would a regular `DatastoreOperations` with an exception:
776775

777776
- It cannot perform sub-transactions.
@@ -861,7 +860,7 @@ Filtering parameters can be of types supported by your configured custom convert
861860
[source, java]
862861
----
863862
public interface TradeRepository extends DatastoreRepository<Trade, String[]> {
864-
List<Trader> findByAction(String action);
863+
List<Trader> findByAction(String action);
865864
866865
int countByAction(String action);
867866
@@ -892,7 +891,8 @@ Cloud Datastore only supports filter components joined by AND, and the following
892891
After writing a custom repository interface specifying just the signatures of these methods, implementations are generated for you and can be used with an auto-wired instance of the repository.
893892
Because of Cloud Datastore's requirement that explicitly selected fields must all appear in a composite index together, `find` name-based query methods are run as `SELECT *`.
894893

895-
Delete queries are also supported. For example, query methods such as `deleteByAction` or `removeByAction` delete entities found by `findByAction`.
894+
Delete queries are also supported.
895+
For example, query methods such as `deleteByAction` or `removeByAction` delete entities found by `findByAction`.
896896
Delete queries are executed as separate read and delete operations instead of as a single transaction because Cloud Datastore cannot query in transactions unless ancestors for queries are specified.
897897
As a result, `removeBy` and `deleteBy` name-convention query methods cannot be used inside transactions via either `performInTransaction` or `@Transactional` annotation.
898898

@@ -902,13 +902,11 @@ Delete queries can have the following return types:
902902
* A collection of entities that were deleted
903903
* 'void'
904904

905-
Methods can have `org.springframework.data.domain.Pageable` parameter to control pagination and sorting,
906-
or `org.springframework.data.domain.Sort` parameter to control sorting only.
905+
Methods can have `org.springframework.data.domain.Pageable` parameter to control pagination and sorting, or `org.springframework.data.domain.Sort` parameter to control sorting only.
907906
See https://docs.spring.io/spring-data/data-commons/docs/current/reference/html/#repositories.query-methods[Spring Data documentation] for details.
908907

909908
For returning multiple items in a repository method, we support Java collections as well as `org.springframework.data.domain.Page` and `org.springframework.data.domain.Slice`.
910-
If a method's return type is `org.springframework.data.domain.Page`, the returned object will include current page,
911-
total number of results and total number of pages.
909+
If a method's return type is `org.springframework.data.domain.Page`, the returned object will include current page, total number of results and total number of pages.
912910

913911
NOTE: Methods that return `Page` execute an additional query to compute total number of pages.
914912
Methods that return `Slice`, on the other hand, don't execute any additional queries and therefore are much more efficient.
@@ -948,14 +946,16 @@ The following parameter types are supported:
948946
* `java.lang.Double`
949947
* `java.lang.Long`
950948
* `java.lang.String`
951-
* `enum` values. These are queried as `String` values.
949+
* `enum` values.
950+
These are queried as `String` values.
952951

953952
With the exception of `Cursor`, array forms of each of the types are also supported.
954953

955954
If you would like to obtain the count of items of a query or if there are any items returned by the query, set the `count = true` or `exists = true` properties of the `@Query` annotation, respectively.
956955
The return type of the query method in these cases should be an integer type or a boolean type.
957956

958-
Cloud Datastore provides provides the `SELECT __key__ FROM ...` special column for all kinds that retrieves the `Key`s of each row. Selecting this special `__key__` column is especially useful and efficient for `count` and `exists` queries.
957+
Cloud Datastore provides provides the `SELECT __key__ FROM ...` special column for all kinds that retrieves the `Key`s of each row.
958+
Selecting this special `__key__` column is especially useful and efficient for `count` and `exists` queries.
959959

960960
You can also query for non-entity types:
961961

@@ -1034,7 +1034,8 @@ DatastoreRepository myRepo;
10341034
public String doWorkInsideTransaction() {
10351035
return myRepo.performTransaction(
10361036
transactionDatastoreRepo -> {
1037-
// work with the single-transaction transactionDatastoreRepo here. This is a DatastoreRepository object.
1037+
// Work with the single-transaction transactionDatastoreRepo here.
1038+
// This is a DatastoreRepository object.
10381039
10391040
return "transaction completed";
10401041
}
@@ -1044,7 +1045,8 @@ public String doWorkInsideTransaction() {
10441045

10451046
==== Projections
10461047

1047-
Spring Data Cloud Datastore supports {spring-data-commons-ref}/#projections[projections]. You can define projection interfaces based on domain types and add query methods that return them in your repository:
1048+
Spring Data Cloud Datastore supports {spring-data-commons-ref}/#projections[projections].
1049+
You can define projection interfaces based on domain types and add query methods that return them in your repository:
10481050

10491051
[source, java]
10501052
----

0 commit comments

Comments
 (0)