eclipse-formatter.properties

#
# Eclipse JDT formatter settings used by the Spotless "eclipse" step.
#
# PURPOSE
# -------
# Prettier (prettier-plugin-java) formats the Java *code*, but it does not format the content of
# Javadoc comments - it only re-indents them. This profile is therefore used for one thing only:
# formatting Javadoc comments as close to IntelliJ IDEA's "Reformat Code" (the format we previously
# used as the Eclipse formatter allows.
#
# The Eclipse step runs BEFORE Prettier in the Spotless step list. Eclipse also re-lays-out the
# code (it cannot be told to skip the code), but Prettier runs afterwards and restores the
# canonical code style, while leaving the formatted Javadoc alone. The code related settings at the
# bottom of this file are therefore only chosen so that Eclipse does not introduce changes that
# Prettier would preserve (blank lines), and so that the Javadoc line-wrapping is computed with the
# same indentation that Prettier uses (2 spaces).
#
# The Javadoc settings mirror the IntelliJ IDEA *default* code style (Editor > Code Style > Java >
# JavaDoc), since the project does not ship a custom IntelliJ scheme.
#
# Known differences from IntelliJ that the Eclipse formatter cannot express:
#   - IntelliJ inserts <p> on blank Javadoc lines, the Eclipse formatter never does.
#   - The first line of a paragraph that starts with <p> ends up ~4 characters shorter than the
#     line length, because Eclipse wraps the text with the <p> included and the tag is moved to
#     its own line afterwards (see the note below).
#
# Note! Eclipse re-flows a paragraph as one unit, which moves <p>, <pre> and </pre> onto the
# neighbouring text line, and it puts all list content in the same column as the surrounding text.
# OTP keeps these tags on their own lines and indents list items, so the Spotless configuration in
# the root pom.xml has a few 'replaceRegex' steps that restore this after this formatter has run:
# list content is indented by two spaces per nesting level (up to two levels) and the continuation
# lines of a wrapped list item get four more spaces so that they line up with the item text. Since
# Eclipse wraps the text before the indentation is added, list lines can end up slightly wider than
# the line length below (a handful of lines reach ~106 characters).
#

# ---------------------------------------------------------------------------------------------
# Javadoc - this is the part we actually want from this formatter
# ---------------------------------------------------------------------------------------------

# Format Javadoc comments only. Line comments (//), block comments (/* */) and the file header are
# left untouched, mirroring IntelliJ's "Enable JavaDoc formatting" which only applies to Javadoc.
org.eclipse.jdt.core.formatter.comment.format_javadoc_comments=true
org.eclipse.jdt.core.formatter.comment.format_block_comments=false
org.eclipse.jdt.core.formatter.comment.format_line_comments=false
org.eclipse.jdt.core.formatter.comment.format_header=false

# Split lines longer than this, counted from the start of the line (not from the comment start).
# 100 matches the Prettier 'printWidth' used for the code.
org.eclipse.jdt.core.formatter.comment.line_length=100
org.eclipse.jdt.core.formatter.comment.count_line_length_from_starting_position=false

# Re-flow paragraphs like IntelliJ does: lines are joined and re-split at the line length above,
# instead of only splitting lines that are too long (which leaves short leftover lines behind).
org.eclipse.jdt.core.formatter.join_lines_in_comments=true

# Recognize HTML so that the content of <pre> blocks is left alone. Code inside <pre> and
# {@code ...} is never re-formatted.
#
# This is the way to keep a block of text (CSV samples, ASCII tables, code, ...) exactly as
# written - wrap it in a <pre> block. Note! The block MUST be closed, an unterminated <pre> is
# not recognized and the text is re-flowed like normal prose:
#
#   /**
#    * <pre>
#    * id, monday, tuesday, start_date, end_date
#    * MONDAY ,1,0,2025-01-01,2030-12-31
#    * </pre>
#    */
#
#    or like this with new Javadoc format.
#
#    /// ```
#    /// id, monday, tuesday, start_date, end_date
#    /// MONDAY ,1,0,2025-01-01,2030-12-31
#    /// ```
#
org.eclipse.jdt.core.formatter.comment.format_html=true
org.eclipse.jdt.core.formatter.comment.format_source_code=false

# IntelliJ: "Align parameter descriptions" / "Align thrown exception descriptions". The 'grouped'
# variant aligns the descriptions of consecutive tags of the same type, without padding the tag
# name itself - this is what IntelliJ does.
org.eclipse.jdt.core.formatter.comment.align_tags_descriptions_grouped=true
org.eclipse.jdt.core.formatter.comment.align_tags_names_descriptions=false
org.eclipse.jdt.core.formatter.comment.indent_parameter_description=false
org.eclipse.jdt.core.formatter.comment.indent_root_tags=false

# IntelliJ: "Blank line after description" = on, but no blank lines between the individual tags.
org.eclipse.jdt.core.formatter.comment.insert_new_line_before_root_tags=insert
org.eclipse.jdt.core.formatter.comment.insert_new_line_between_different_tags=do not insert
org.eclipse.jdt.core.formatter.comment.insert_new_line_for_parameter=do not insert
org.eclipse.jdt.core.formatter.comment.javadoc_do_not_separate_block_tags=true

# IntelliJ: "Keep empty lines" = on, and /** and */ are always placed on their own lines.
org.eclipse.jdt.core.formatter.comment.clear_blank_lines_in_javadoc_comment=false
org.eclipse.jdt.core.formatter.comment.new_lines_at_javadoc_boundaries=true
org.eclipse.jdt.core.formatter.comment.preserve_white_space_between_code_and_line_comments=true

# Use <pre> tags or code blocks in new Javadoc style to prevent formatting
org.eclipse.jdt.core.formatter.use_on_off_tags=false

# ---------------------------------------------------------------------------------------------
# Code - only here to keep Eclipse from making changes that would survive the Prettier step
# ---------------------------------------------------------------------------------------------

# Same indentation as Prettier (tabWidth=2, useTabs=false), so the Javadoc wrapping is computed at
# the column the comment will actually end up in.
org.eclipse.jdt.core.formatter.tabulation.char=space
org.eclipse.jdt.core.formatter.tabulation.size=2
org.eclipse.jdt.core.formatter.indentation.size=2
org.eclipse.jdt.core.formatter.continuation_indentation=2
org.eclipse.jdt.core.formatter.continuation_indentation_for_array_initializer=2
org.eclipse.jdt.core.formatter.lineSplit=100

# Prettier preserves existing blank lines (collapsing runs into one) but never inserts new ones, so
# Eclipse must not insert any either - its blank lines would otherwise survive into the result.
org.eclipse.jdt.core.formatter.number_of_empty_lines_to_preserve=1
org.eclipse.jdt.core.formatter.blank_lines_before_package=0
org.eclipse.jdt.core.formatter.blank_lines_after_package=0
org.eclipse.jdt.core.formatter.blank_lines_before_imports=0
org.eclipse.jdt.core.formatter.blank_lines_after_imports=0
org.eclipse.jdt.core.formatter.blank_lines_between_import_groups=0
org.eclipse.jdt.core.formatter.blank_lines_between_type_declarations=0
org.eclipse.jdt.core.formatter.blank_lines_before_first_class_body_declaration=0
org.eclipse.jdt.core.formatter.blank_lines_after_last_class_body_declaration=0
org.eclipse.jdt.core.formatter.blank_lines_before_field=0
org.eclipse.jdt.core.formatter.blank_lines_before_method=0
org.eclipse.jdt.core.formatter.blank_lines_before_abstract_method=0
org.eclipse.jdt.core.formatter.blank_lines_before_member_type=0
org.eclipse.jdt.core.formatter.blank_lines_before_new_chunk=0
org.eclipse.jdt.core.formatter.blank_lines_at_beginning_of_method_body=0
org.eclipse.jdt.core.formatter.blank_lines_at_end_of_method_body=0
org.eclipse.jdt.core.formatter.blank_lines_at_beginning_of_code_block=0
org.eclipse.jdt.core.formatter.blank_lines_at_end_of_code_block=0
org.eclipse.jdt.core.formatter.blank_lines_before_code_block=0
org.eclipse.jdt.core.formatter.blank_lines_after_code_block=0
org.eclipse.jdt.core.formatter.blank_lines_between_statement_group_in_switch=0

# Leave the code layout to Prettier.
org.eclipse.jdt.core.formatter.join_wrapped_lines=false
org.eclipse.jdt.core.formatter.never_indent_block_comments_on_first_column=true
org.eclipse.jdt.core.formatter.never_indent_line_comments_on_first_column=true