[SourceKit] restore __raw_doc_comment identifier

[keith]

This identifier can be used with sourcekit related tools to find doc
comments.

This reverts c78f169

Resolves SR-2487

[keith]

I'll need some more test fixture updates if it makes sense to move forward with this.

[CodaFi]

@bitjammer @akyrtzi Can anyone provide some background about why this was originally struck out as an "implementation detail"?

[akyrtzi]

The presence of an __raw_doc_comment "attribute" is implementation detail of the AST.
If the intended functionality is to indicate that there's a doc comment attached to that entity then we should introduce a new field like key.has_doc_comment or even better provide the source range for the doc-comment like, key.doc_comment_offset and key.doc_comment_length.

To that end I'd prefer not to accept this PR as it currently stands.

[jpsim]

or even better provide the source range for the doc-comment like, key.doc_comment_offset and key.doc_comment_length.

This would be amazing. That's been an idea I've had for a while, since the string and AST processing I resort to in SourceKitten to accomplish this are hacky and full of edge cases.

[CodaFi]

Alright. Given that I think I'll close this one for now.

@jpsim Do you have an idea of what needs to be changed here?

[jpsim]

Nothing more than what @akyrtzi shared above.

Since SourceKit already extracts and processes doc comments (key.doc.full_as_xml), it would be a matter of looking at what that code does and extract just relevant bits to re-expose its offset and length.

[keith]

What cases are full_as_xml present? It seems to me like that is not always the case, where it was with __raw_doc_comment

[jpsim]

I think that's only available after indexing, unlike the old raw key. (SwiftLint doesn't use the index btw)