Thanks for the request, and the analysis.

I think if there's a way of presenting all relevant doc comments such that no context is lost, we'd welcome it.

Considering the suggestion:

const O_TRUNC int = 512
os.O_TRUNC on pkg.go.dev

Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.
    
truncate regular writable file when opened.

One problem I see with this is that the last sentence looks out of place: absent context it's not entirely clear what it's modifying. This isn't that egregious an example, but one can imagine other cases where the spec.Comment is even more out of place.

I wonder if we should format an abbreviated declaration. Perhaps something like this?

// Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.
const (
  O_TRUNC int = 512 // truncate regular writable file when opened.
  // ...and N other values
)

We're unlikely to have time to prioritize this soon, but we'd welcome a contribution. However, before contributing we should decide on an ideal presentation here.

We've just discussed this issue, and consensus was that formatting a truncated form of the full const decl (as shown in #48200 (comment)) makes sense. However, it isn't something we're likely to work on soon, so leaving this as 'help wanted'.

Hi @findleyr, thanks for the reply. With respect to your suggestion, I think it's reasonable but there are some problems around:

// Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.
const (
O_TRUNC int = 512 // truncate regular writable file when opened.
// ...and N other values
)

1. if the ...and N other values means the extra declaration, the hover results may exceed what users want to see, especially when there are hundreds of declarations, eg.
   https://github.com/golang/tools/blob/master/internal/lsp/protocol/tsprotocol.go#L4914-L5366.

2. currently the hover results are presented with the format of [signature]\n[link]\n[documentation], do we need to keep following this style? For example, move the general comments down and keep the rest comments as they are, like this:
   // this may still lose some context but more descriptive than original one.

const (
    O_TRUNC int = 512 // truncate regular writable file when opened.
)
os.O_TRUNC on pkg.go.dev
Flags to OpenFile wrapping those of the underlying system. Not all flags may be implemented on a given system.

As there seems no relevant documentation which explicitly defines commentary specification, I use this picture to explain the corresponding comment scope in my view:

Based on above, I think we can change the signature of the const/var declaration to make it's presentation more comprehensive.

It's unrealistic to restraint user's comment behaviour without mechanical check but currently gopls can try to make all context present.

9/23 update: The old deisgn is too miscellaneous and may not deserve too much work to implement. In order to unify the presentation style, make decl.Doc always(if has) at the position of documentation and the rest like findleyr suggested.

I will work on it next few days and paste the capture of hover result here.

#### 1. only one of the three comments(decl.Doc/spec.Doc/spec.Comment) are added.
In this case we can keep the original presentation.

#### 2. two of the three comments are added.
#### 2.1 decl.Doc and one of the rest two are added.
In this case like findleyr suggested, use abbreviated declaration with decl.Doc as documentation part.

#### 2.2 spec.Doc and spec.Comment are added.
In this case we use spec.Doc as documentation part and keep spec.Comment in signature.

#### 3 all three comments are added.
Similar to 2.2, use decl.Doc as Documentation and the rest in signature.