Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SR-15765] CLI option for choosing level of access to expose when assembling documentation for internal consumption #11

Open
heckj opened this issue Jan 23, 2022 · 2 comments
Labels
enhancement New feature or request

Comments

@heckj
Copy link

heckj commented Jan 23, 2022

Previous ID SR-15765
Radar None
Original Reporter @heckj
Type Improvement
Additional Detail from JIRA
Votes 0
Component/s Swift-DocC
Labels Improvement
Assignee None
Priority Medium

md5: 1e2f20aa46123585b94e4a67226c6fb4

Issue Description:

The current `swift-docc-plugin` has some code to choose a level of protection to use when generating a symbol graph (apple/swift-docc-plugin/blob/main/Plugins/SharedPackagePluginExtensions/Target+defaultSymbolGraphOptions.swift#L16) - currently it's using `public` for libraries and `internal` for executables.

I'd like to be able to make this choice explicitly for the use case of generating internal documentation, so that libraries and/or executables could include not just `internal`, but also `private` methods that are documented.

I inquired in the forums about the potential to add a command line option to the swift-docc-plugin interface to allow this, and opening a bug was suggested as a means to dig into this.

I don't have a firm proposal for the CLI option name, but wanted to suggest `--access level` as a possible option. I was thinking this could either override the specific access level returned from `defaultSymbolGraphOptions` (preserving the other defaults it provides:

  • includeSynthesized: true

  • includeSPI: false
    ) or if the option was invoked could be explicitly checked and the options passed into `getSymbolGraph` within `SwfitDoccConvert`.

If it would be preferable to include three (optional!) command line options, one for each of the possible symbol graph options (access level, includeSynthesized, and includeSPI), I'd be happy to try and cobble that together as well, building off the defaults already in place. My initial instinct is that access level is the one that I'd like to be able expose for internal docs, but I also don't use the `SPI` marker within my libraries.

@swift-ci swift-ci transferred this issue from apple/swift-issues Apr 25, 2022
@shahmishal shahmishal transferred this issue from apple/swift May 3, 2022
@d-ronnqvist
Copy link

@ethan-kusters should this issue move to https://github.com/apple/swift-docc-plugin ?

@ethan-kusters ethan-kusters transferred this issue from apple/swift-docc May 10, 2022
@ethan-kusters
Copy link
Collaborator

@ethan-kusters should this issue move to https://github.com/apple/swift-docc-plugin ?

Good catch- thanks @d-ronnqvist!

@ethan-kusters ethan-kusters added enhancement New feature or request and removed improvement labels May 10, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

3 participants