Make javadoc <p> style guide compliant

This led to confusion for an open source contributor about how to format
code. We don't want to be like, "do as I say, not as I do."

https://google.github.io/styleguide/javaguide.html#s7.1.2-javadoc-paragraphs
-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=122589700
This commit is contained in:
Justine Tunney 2016-05-17 18:56:33 -07:00
parent 4854f875b0
commit 6f4b059cc9
79 changed files with 395 additions and 386 deletions

View file

@ -22,9 +22,9 @@ public interface Command {
/**
* Marker interface for commands that use the remote api.
* <p>
* Just implementing this is sufficient to use the remote api; {@link RegistryTool} will install
* it as needed.
*
* <p>Just implementing this is sufficient to use the remote api; {@link RegistryTool} will
* install it as needed.
*/
public interface RemoteApiCommand extends Command {}

View file

@ -54,15 +54,14 @@ import java.util.List;
/**
* Command for creating new auction credits based on a CSV file from Pool.
* <p>
* The CSV file from the auction provider uses double-quotes around every field, so in order to
*
* <p>The CSV file from the auction provider uses double-quotes around every field, so in order to
* extract the raw field value we strip off the quotes after splitting each line by commas. We are
* using a simple parsing strategy that does not support embedded quotation marks, commas, or
* newlines.
* <p>
* TODO(b/16009815): Switch this file to using a real CSV parser.
* <p>
* Example file format:
*
* <p>Example file format:
*
* <pre>
* "Affiliate","DomainName","Email","BidderId","BidderStatus","UpdatedAt",
* "SalePrice","Commissions","CurrencyCode"
@ -71,12 +70,14 @@ import java.util.List;
* "reg2","foo.xn--q9jyb4c","email2@example.net","???_64","WIN","4/3/2014 7:13:09 PM",
* "1000.0000","40.0000","JPY"
* </pre>
* We only care about three fields: 1) the "Affiliate" field which corresponds to the registrar
* clientId stored in datastore, and which we use to determine which registrar gets the credit,
* 2) the "Commissions" field which contains the amount of the auction credit (as determined by
* logic on the auction provider's side, see the Finance Requirements Doc for more information), and
* 3) the "CurrencyCode" field, which we validate matches the TLD-wide currency for this TLD.
*
* <p>We only care about three fields: 1) the "Affiliate" field which corresponds to the registrar
* clientId stored in datastore, and which we use to determine which registrar gets the credit, 2)
* the "Commissions" field which contains the amount of the auction credit (as determined by logic
* on the auction provider's side, see the Finance Requirements Doc for more information), and 3)
* the "CurrencyCode" field, which we validate matches the TLD-wide currency for this TLD.
*/
// TODO(b/16009815): Switch this file to using a real CSV parser.
@Parameters(separators = " =", commandDescription = "Create new auction credits based on CSV")
final class CreateAuctionCreditsCommand extends MutatingCommand {

View file

@ -146,8 +146,8 @@ final class MakeBillingTablesCommand extends BigqueryCommand {
* Generates a view of registrar credit balance entities that collapses them down to the one
* 'true' credit balance for a given credit ID and effective time, eliminating any duplicates by
* choosing the most recently written balance entry of the set.
* <p>
* The result is a list of the historical balances of each credit (according to the most recent
*
* <p>The result is a list of the historical balances of each credit (according to the most recent
* data written) that can be used to find the active balance of a credit at any point in time.
*/
private void makeCreditBalanceView() throws Exception {

View file

@ -130,10 +130,10 @@ public abstract class MutatingCommand extends ConfirmingCommand implements Remot
/**
* Initializes the command.
* <p>
* Subclasses override this method to populate {@link #changedEntitiesMap} with updated
* entities. The old entity is the key and the new entity is the value; the key is null for
* newly created entities and the value is null for deleted entities.
*
* <p>Subclasses override this method to populate {@link #changedEntitiesMap} with updated
* entities. The old entity is the key and the new entity is the value; the key is null for newly
* created entities and the value is null for deleted entities.
*/
@Override
protected abstract void init() throws Exception;

View file

@ -85,8 +85,8 @@ final class UpdateApplicationStatusCommand extends MutatingCommand {
/**
* Stages changes to update the status of an application and also enqueue a poll message for the
* status change, which may contain a PendingActionNotificationResponse if this is a final status.
* <p>
* This method must be called from within a transaction.
*
* <p>This method must be called from within a transaction.
*/
private void updateApplicationStatus(String applicationId) {
ofy().assertInTransaction();

View file

@ -35,8 +35,8 @@ public final class DateTimeParameter extends ParameterConverterValidator<DateTim
* Parser for DateTimes that permits only a restricted subset of ISO 8601 datetime syntax.
* The supported format is "YYYY-MM-DD'T'HH:MM:SS[.SSS]ZZ", i.e. there must be a complete date
* and at least hours, minutes, seconds, and time zone; milliseconds are optional.
* <p>
* We use this instead of the default {@link ISODateTimeFormat#dateTimeParser()} because that
*
* <p>We use this instead of the default {@link ISODateTimeFormat#dateTimeParser()} because that
* parser is very flexible and accepts date times with missing dates, missing dates, and various
* other unspecified fields that can lead to confusion and ambiguity.
*/

View file

@ -18,8 +18,8 @@ import java.util.logging.Level;
/**
* Java logging level CLI parameter converter/validator.
* <p>
* If Level were an enum then this wouldn't be needed since JCommander has built-in conversion
*
* <p>If Level were an enum then this wouldn't be needed since JCommander has built-in conversion
* support for enums, but Level is actually just a regular class with some static instances.
*/
public final class LoggingLevelParameter extends ParameterConverterValidator<Level> {

View file

@ -30,15 +30,16 @@ import java.util.Map;
/**
* Combined converter and validator class for transition list JCommander argument strings.
* <p>
* These strings have the form {@code <DateTime>=<T-str>,[<DateTime>=<T-str>]*} where
* {@code <T-str>} is a string that can be parsed into an instance of some value type {@code T},
* and the entire argument represents a series of timed transitions of some property taking on
* those values. This class converts such a string into an ImmutableSortedMap mapping DateTime to
* {@code T}. Validation and conversion share the same logic; validation is just done by attempting
*
* <p>These strings have the form {@code <DateTime>=<T-str>,[<DateTime>=<T-str>]*} where
* {@code <T-str>} is a string that can be parsed into an instance of some value type {@code T}, and
* the entire argument represents a series of timed transitions of some property taking on those
* values. This class converts such a string into an ImmutableSortedMap mapping DateTime to
* {@code T}. Validation and conversion share the same logic; validation is just done by attempting
* conversion and throwing exceptions if need be.
* <p>
* Subclasses must implement parseValue() to define how to parse {@code <T-str>} into a {@code T}.
*
* <p>Subclasses must implement parseValue() to define how to parse {@code <T-str>} into a
* {@code T}.
*
* @param <T> instance value type
*/

View file

@ -76,8 +76,8 @@ public abstract class ListObjectsAction<T extends ImmutableObject> implements Ru
/**
* Returns an {@link ImmutableBiMap} that maps any field name aliases to the actual field names.
* <p>
* Users can select aliased fields for display using either the original name or the alias. By
*
* <p>Users can select aliased fields for display using either the original name or the alias. By
* default, aliased fields will use the alias name as the header instead of the original name.
*/
ImmutableBiMap<String, String> getFieldAliases() {
@ -89,11 +89,11 @@ public abstract class ListObjectsAction<T extends ImmutableObject> implements Ru
* will override, for any overlapping field names, the default behavior of getting the field
* value by looking up that field name in the map returned by
* {@link ImmutableObject#toDiffableFieldMap}.
* <p>
* This can be used to specify customized printing of certain fields (e.g. to print out a boolean
* field as "active" or "-" instead of "true" or "false"). It can also be used to add fields to
* the data, e.g. for computed fields that can be accessed from the object directly but aren't
* stored as simple fields.
*
* <p>This can be used to specify customized printing of certain fields (e.g. to print out a
* boolean field as "active" or "-" instead of "true" or "false"). It can also be used to add
* fields to the data, e.g. for computed fields that can be accessed from the object directly but
* aren't stored as simple fields.
*/
ImmutableMap<String, String> getFieldOverrides(@SuppressWarnings("unused") T object) {
return ImmutableMap.of();
@ -269,8 +269,8 @@ public abstract class ListObjectsAction<T extends ImmutableObject> implements Ru
/**
* Returns for the given column widths map a row formatting function that converts a row map (of
* column keys to cell values) into a single string with each column right-padded to that width.
* <p>
* The resulting strings separate padded fields with two spaces and each end in a newline.
*
* <p>The resulting strings separate padded fields with two spaces and each end in a newline.
*/
private static Function<Map<String, String>, String> makeRowFormatter(
final Map<String, Integer> columnWidths) {