# (SymbolGraphGen) can we make \`isImplicitlyPrivate\` checking configurable?

**URL:** <https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781>\
**Category:** Swift-DocC\
**Tags:** symbolgraphgen\
**Created:** [March 8, 2022, 1:37am UTC](https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781 "2022-03-08T01:37:56Z")\
**Posts on this page:** 5\
**Page:** 1

<div class="post-metadata">

**Author:** ![taylorswift](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/taylorswift/32/43413_2.png) [@taylorswift](https://forums.swift.org/u/taylorswift)\
**Post date:** [March 8, 2022, 1:37am UTC](https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781/1 "2022-03-08T01:37:56Z")

</div>

the `SymbolGraphGen` tool currently offers no way to enable cataloguing of unconditionally-unavailable symbols, and underscored standard library symbols. (this checking is done by [`isImplicitlyPrivate`](https://github.com/apple/swift/blob/62575ed77c220dbf5f4533b8625664f63a14b59c/lib/SymbolGraphGen/SymbolGraph.cpp#L686) in `SymbolGraph.cpp`.)

one implication of this is that sometimes we get holes in the generated symbolgraphs where edges are referencing USRs that the symbolgraph generator omitted. pruning edges that have one endpoint referencing an omitted symbol isn’t a solution, because a lot of standard library types use underscored protocols to vend public (“synthesized”) APIs on public types.

from an educational standpoint, it’s also sometimes valuable to catalog symbols that are unconditionally `unavailable` everywhere, if only to inform API users that the symbol has moved.

could we get an option to opt-out of the `isImplicitlyPrivate` checking? flagging implicitly private symbols is often better done in a higher layer of tooling.

---

<div class="post-metadata">

**Author:** ![franklin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/franklin/32/17924_2.png) [@franklin](https://forums.swift.org/u/franklin)\
**Post date:** [March 9, 2022, 1:00pm UTC](https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781/2 "2022-03-09T13:00:24Z")

</div>

The intent for prefixing an API name with an underscore is usually to indicate that the API shouldn't be used by clients (some IDEs don't surface them as part of code completion for instance), so personally I don't think they're relevant _by default_ in documentation. However, I'm all for extra customization to opt-out of this behavior for symbol graph files, including for using SGFs for non-documentation purposes. Would be super helpful to have a ticket for this to make sure we don't lose track of it! If you're interested in adding that support, @QuietMisdreavus and I would be more than happy to provide some pointers.

---

<div class="post-metadata">

**Author:** ![taylorswift](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/taylorswift/32/43413_2.png) [@taylorswift](https://forums.swift.org/u/taylorswift)\
**Post date:** [March 9, 2022, 10:15pm UTC](https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781/3 "2022-03-09T22:15:08Z")

</div>

> [@franklin](#):
>
> The intent for prefixing an API name with an underscore is usually to indicate that the API shouldn't be used by clients (some IDEs don't surface them as part of code completion for instance), so personally I don't think they're relevant _by default_ in documentation.

they are not relevant in _documentation_, but SymbolGraphGen isn’t a documentation generator, it’s a serializer whose outputs documentation generators use to generate documentation. the holes in the symbol graphs are a major problem for such tooling (including [`swift-biome`](https://github.com/kelvin13/swift-biome)) because they impede certain optimizatons and break invariants that they rely on in order to serve large amounts of documentation at scale. although the end consumer of documentation will never see the hidden APIs, they are important for the tooling’s internal data model.

for example, `swift-biome` currently de-duplicates synthesized members against their generic base, since not doing so leads to quadratic explosion of synthesized symbols when protocols contain many extension members (like [`Sequence`](https://swiftinit.org/reference/swift/sequence)) and also have many conformers (like [`Sequence`](https://swiftinit.org/reference/swift/sequence)). this is part of the reason why [`SwiftSyntax`’s symbol graph is 2 orders of magnitude larger than a typical library](https://forums.swift.org/t/why-is-the-generated-symbolgraph-for-swiftsyntax-so-large/55720). however, this optimization is not possible if `swift-biome` doesn’t know about the generic base in the first place, because it was part of an underscored API.

> [@franklin](#):
>
> If you're interested in adding that support, @QuietMisdreavus and I would be more than happy to provide some pointers.

yeah, i can implement it in a PR, i was just asking here to see if this was a change that has a good chance of getting accepted.

> [@franklin](#):
>
> Would be super helpful to have a ticket for this to make sure we don't lose track of it!

i don’t know where the issue tracker for SymbolGraphGen lives. should i just file it on [bugs.swift.org](http://bugs.swift.org) as a compiler issue?

---

<div class="post-metadata">

**Author:** ![franklin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/franklin/32/17924_2.png) [@franklin](https://forums.swift.org/u/franklin)\
**Post date:** [March 10, 2022, 8:57am UTC](https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781/4 "2022-03-10T08:57:38Z")

</div>

A new flag or flags to opt out of this behaviour sounds reasonable to me. Maybe something in the lines of `-include-implicitly-private-symbols` and `-include-unconditionally-unavailable-symbols`?

And yes, [bugs.swift.org](http://bugs.swift.org) is where we track symbol graph bugs.

---

<div class="post-metadata">

**Author:** ![franklin](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/franklin/32/17924_2.png) [@franklin](https://forums.swift.org/u/franklin)\
**Post date:** [March 21, 2022, 11:27am UTC](https://forums.swift.org/t/symbolgraphgen-can-we-make-isimplicitlyprivate-checking-configurable/55781/5 "2022-03-21T11:27:02Z")

</div>

FWIW I just stumbled upon this in [TSPL](https://docs.swift.org/swift-book/ReferenceManual/LexicalStructure.html#ID412):

> Treat identifiers that begin with an underscore as internal, even if their declaration has the public access-level modifier. This convention lets framework authors mark part of an API that clients must not interact with or depend on, even though some limitation requires the declaration to be public. In addition, identifiers that begin with two underscores are reserved for the Swift compiler and standard library.

…which I think solidifies the argument for not including underscored symbols in SGFs by default when extracting SGFs with _public_ visibility. Nonetheless, having this behavior configurable is still useful.
