palantir / palantir/palantir-java-format

Support re-writing multiline docstrings into their multiline form

Open
#974 5 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
907
Forks
101
Avg merge
1d 3h
Merged PRs (30d)
19

Description

I often wish that people would write something like:

    /** Returns true if the argument should be optional when fully parsed. */
    public static boolean optionalWhenFullyParsed(Argument<?, ?> argument) {
        return argument.isOptional() && argument.defaultValue().isEmpty();
    }

rather than:

    /**
     * Returns true if the argument should be optional when fully parsed.
     */
    public static boolean optionalWhenFullyParsed(Argument<?, ?> argument) {
        return argument.isOptional() && argument.defaultValue().isEmpty();
    }

We could compute whether it would fit on one line and rewrite it if it would. This would only apply to the case of multi-line docstrings that contain a single line. i.e. it would not include:

    /**
     * This is
     * a silly 
     * docstring.
     */
    public static boolean example()

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no files or tests; begin by tracing the formatter entry point that handles Java docstrings. Use the single-line and multiline examples as behavioral cases, preserving multiline docstrings with multiple content lines and rewriting only single-line content that fits on one line.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.