Swift-symbolgraph-extract loses fragmented doccomments

Development Swift-DocC
1

it looks like if there are any interceding two-slash comments between a doccomment and a declaration, swift-symbolgraph-extract will discard the doccomment, making it look as if the symbol lacks documentation. for example, in the swift-system package:

...
/// However, the rules for path equivalence
/// are file-system–specific and have additional considerations
/// like case insensitivity, Unicode normalization, and symbolic links.
///
// TODO(docs): Section on all the new syntactic operations, lexical normalization, decomposition,
// components, etc.
/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
public struct FilePath {

but i’m only getting:

{
  "kind": {
    "identifier": "swift.struct",
    "displayName": "Structure"
  },
  "identifier": {
    "precise": "s:13SystemPackage8FilePathV",
    "interfaceLanguage": "swift"
  },
  "pathComponents": [
    "FilePath"
  ],
  "names": {
    "title": "FilePath",
    "navigator": [
      {
        "kind": "identifier",
        "spelling": "FilePath"
      }
    ],
    "subHeading": [
      {
        "kind": "keyword",
        "spelling": "struct"
      },
      {
        "kind": "text",
        "spelling": " "
      },
      {
        "kind": "identifier",
        "spelling": "FilePath"
      }
    ]
  },
  "declarationFragments": [
    {
      "kind": "keyword",
      "spelling": "struct"
    },
    {
      "kind": "text",
      "spelling": " "
    },
    {
      "kind": "identifier",
      "spelling": "FilePath"
    }
  ],
  "accessLevel": "public",
  "location": {
    "uri": "file:///.../swift-system/Sources/System/FilePath/FilePath.swift",
    "position": {
      "line": 43,
      "character": 14
    }
  }
}
2

FWIW, that's not just swift-symbolgraph-extract. The behavior everywhere in the compiler AFAIK is that a documentation comment must occur immediately before the declaration with no other interceding comments (only whitespace is allowed). SourceKit obeys the same logic—if you have a struct written like the one above and access its quick help in Xcode, it doesn't see it either.

3

the apple docs don’t appear to be affected by this issue, how are they collecting doc comments?

4

Someone from Apple would have to confirm the details, but there are two versions of the "System" APIs. The first is distributed with the OS and has the module name System, and AFAIK the docs you linked to correspond to those (since they have OS availability that corresponds to when they first were introduced). The others are the open-source package, with the module name SystemPackage. My guess is that the source of the OS-included library doesn't have the interfering non-doc comments?

1 Like
5

RIP. looks like i’m going to have to drop down to the swift-syntax level…

6

You are correct, the OS library source does not have the todo comments and the availability comments are replaced with real annotations.

The availability comments can be expanded using a script in the swift-system repo and I think a PR to move that todo would be fine. cc @Michael_Ilseman

1 Like
7

Note there is a swiftlint rule for making sure you don't accidentally do this orphaned_doc_comment Reference

1 Like