Feature Request: Allow Inline Field Documentation in Dart

[KiddoV]

Summary

Currently, Dart does not support inline documentation for class fields or struct-like data models. This limits the ability to add concise, relevant documentation directly beside the field, which is especially useful for quickly understanding models or data structures.

Example (Current Behavior in Dart)

class ModelA {
  final String field1; /// This doc is for field1 (❌ Not recognized)
  final String field2;
}

The inline comment (///) next to field1 is not shown in IntelliSense or on hover in editors like VS Code.

What I want (Inspired by Go)

In Go, this is possible:

type ModelA struct {
    field1 string // Test <== Shown on hover in VS Code
}

Suggested Enhancement
Support inline /// or /** */ documentation next to class fields in Dart, similar to Go-style struct comments. This would help:

• Keep field definitions readable and concise
• Reduce boilerplate (no need to break lines for simple doc comments)
• Improve developer experience when viewing code in editors

Benefits

• Better IntelliSense / hover support for fields
• More natural for data models or DTOs
• Less vertical space wasted for simple field descriptions

Workaround

Right now, we are forced to write:

  /// This doc is for field1
  final String field1;

Thanks!
This would be a small but meaningful DX improvement for Dart/Flutter developers. 🙏

[FMorschel]

CC @bwilkerson

[lrhn]

This would need to be supported both by DartDoc and the analyzer.

Currently all DartDoc is written before the documented entity. If it can be written on the same line as well, then

• What happens if you do both? (Probably ignore the trailing comment, and give a warning that it's unused.)
• What happens if you use /** and span multiple lines?

  int number; /** The number of numbers that are numbering.
  *  
  *  All your number needs are covered by this number.
  */

  Reject? Accept? Force you to put it before the field?
  (I'd be fine with only accepting EOL-doc-comments as trailing, it's an in-line comment! 😉)
• The formatter needs to not reflow trailing comments. It probably already tries to avoid that.
• What happens if you have more than one entity on a line? Probably the same as with pre-comments.

  int number1, number2; /// The numbers of things.

  Do whatever we would do if the comment was before the line. But what if the formatter made it into:

  int number1,
       number2; /// The number of things.

  Is it still a comment for the entire declaration, or just for number2?

  int foo( 
    int x,
    int y,
  ) => 42; /// The foo is bar!

  or

  int foo( 
    int x,
    int y) => 42; /// The foo is bar!

  What if these were originally on one line, but the formatter reflowed them?
  What would it mean? Is the doc-comment not on any entity any more?

May want to have restrictions like:

• Only works if the entire declaration fits on one line. Or if the comment is on the line as the name being declared.
• Only works if there is only one thing being declared on that line (only one name introduced on the line).
• Only works with a /// comment.
• Not allowed to have doc-comment both before and inline.

Then it could probably work.
And it could give a way to document parameters separately, without taking too much vertical space.

Point<int> makePoint( /// Creates a `Point`
   int x, /// The X coordinate.
   int y, /// The Y coordinate.
) => Point<int>.carthesian(x, y);

[bwilkerson]

I'm not convinced that this would actually be an overall improvement for the DX.

On the plus side, it would allow developers more flexibility in terms of where the documentation comment was located. The primary value, as Lasse mentioned, appears to be a reduction in the amount of vertical space required in order to have documentation.

Are there other benefits I'm not seeing?

I can also see some disadvantages.

Dart largely defines white space to not be significant. (I can think of one exception related to metadata and record types, and there might be others.) This would add another exception, and one that might impact more users. We'd need to ensure that neither the formatter nor any of our refactorings changed the location of the comment in a way that would change what it was attached to. (Speaking of which, this would technically be a breaking change, though I expect the number of users impacted by it would be zero.)

This proposal would allow Dart code to be less consistent in that there would now be two places for the documentation for a field (or declaration in general) to be found. That inconsistency might make it harder to read the code because of having to search for a documentation comment, especially if the field declaration is long because of an initializer:

Map<String, String> someLargeTable = {
  'a': 'a',
  // ...
  'z': 'z'
}; /// A mapping from input strings to output strings.

In other words, having the comment on the same line as the declaration would, in my opinion, be a benefit only when they both fit on a single line, and in my experience there are enough cases where they won't to make it a style that couldn't be consistently applied.

Bottom line, even ignoring all of the questions, I'm concerned that the cost of this feature would outweigh the benefit.