Allow certain directives #650
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
emilyychenn
commented
Jun 27, 2023
emilyychenn
commented
- Explanation: Allow some directives in doc comments.
- Scope: Small in scope. Completes a feature that was pitched already.
- GitHub Issue: rdar://111414385 and Allow certain directives in doc comments #591
- Risk: Low risk: isolated change and well-tested.
- Testing: End to end testing with Swift-DocC-Render. Additional unit tests have been added.
- Original PR: Allow certain directives #641
- Reviewer: @ethan-kusters
rdar://107002535
Introduce "HTTPBodyParameter(s)" new tags for ListItemExtractor to identify documentation for the parameters that make up a multipart (or URL-encoded) form. rdar://106389324 Co-authored-by: Peter Wilson <pwilson@apple.com>
…entifier (apple#517) * Fix crash when tutorial named like module/bundle is curated w/ symbol rdar://106958656 * Fix test that was always passing and update misleading comments in test
* Process `typeDetails` information from symbol graphs. Convert data into base-type details and allowed type declarations for `RenderProperty` entities, such as dictionary keys and HTTP parameters. * Update SymbolKit dependency to pick up latest commit.
Updates the instructions to get started with DocC to mention that using the Swift-DocC plugin is the preferred way of using DocC.
…with the same name (apple#534) * Fix crash when exported import protocol is aliased with same name rdar://107623749 * Remove incorrect memberOf relationships in handcrafted test symbol data
Adds a new `@PageColor` metadata directive that allows for
customizing the color used to represent a given page.
`@PageColor` gives authors control over the color used
when rendering a page – initially this will affect the background
color Swift-DocC-Render uses in the page's introduction (hero) section.
Example:
# What's New in SlothCreator
@metadata {
@PageColor(blue)
}
Let's check out what's new in SlothCreator!
...
Details:
`@PageColor` accepts the following parameters:
- `color`: An unnamed parameter that accepts one of the following:
- `blue`: A context-dependent blue color.
- `gray`: A context-dependent gray color.
- `green`: A context-dependent orange color.
- `orange`: A context-dependent orange color.
- `purple`: A context-dependent purple color.
- `red`: A context-dependent red color.
- `yellow`: A context-dependent yellow color.
`@PageColor` is described on the Swift forums here:
https://forums.swift.org/t/support-for-customizing-a-page-s-accent-color-in-swift-docc/64093
Dependencies:
- apple/swift-docc-render#582
rdar://106153042
…isions (apple#540) * Disfavor default implementations and synthesized symbols in link collisions rdar://98781530 * Add link to SymbolKit enhancement request about synthesized symbols
…apple#543) * Store only the resolved reference in DocumentationContext.symbolIndex rdar://106654403 * Add test that references in symbol index have nodes in doc cache
* Fast path to look up resolved references by their absolute string rdar://85531439 * Fix bug where links with special characters used the link as title rdar://85531439 * Skip new test when running old link resolver implementation * Add more type annotations in test to accommodate other compiler versions * Expand the fallback parsing of authored documentation links
apple#548) * Fix inverse logic in hierarchy based link resolver environment opt-out * Check environment value before user default. Also, support more values as true/false for environment configuration.
…e#539) * Fix test waiting for unfulfilled expectation * Fix test that never asserted anything * Support resolving images in convert service requests rdar://107531364
* Warn about expressions that take long to type check in debug builds * Fix slow type checking in test rdar://107960794
Fixes a bug where the `@PageColor` metadata directive was ignored when used on symbol pages. rdar://107962126
apple#541) rdar://107729630 Bundles with extension block symbols generate placeholder "Extended Symbol" pages to automatically curate extension symbols. However, if the symbols are then curated elsewhere, the "Extended Symbol" pages are left confusingly empty. Drop these pages if they have no child pages remaining. An "Extended Symbol" page will remain if an extension markdown file is provided for it, even if its children are curated elsewhere. Links to these dropped pages will generate a warning and be converted to code voice in the final rendering. References in automatically generated symbol-relationship page sections will not generate a warning, but they will be converted to code voice as well.
Updates the logic for `@CallToAction` buttons that are attached to `sampleCode` pages and use the `link` purpose to render with a more specific “View Source” title instead of the more generic “Visit” title. This makes the intent of the button more clear. Resolves rdar://108013602
) * Use link resolution to match documentation extensions with symbols Also, fix incorrect source url in technology root diagnostic rdar://108392613 * Add test for matching language specific documentation extension links * Allow documentation extension links to resolve relative to the module rdar://76252171 * Warn when a documentation extension doesn't match a symbol rdar://108392639 * Expect different behavior in tests when the old link resolver is used * Restore old implementation detail for ConvertService only * Restore test assertion about documentation extension in asset store
…equired for extended documentation to be available rdar://105460209
Includes a fix for generate-symbol-graph doc comment fetching for directives implemented by a class with a different name. rdar://108207445
* Support resolving code file references in ConvertService rdar://107965493 * Support highlighting lines in resolved file assets
…chy have the same name (apple#578) * Walk up the path hierarchy if links fail to resolve in a specific scope rdar://108672152 Also, check the module's scope if the link couldn't otherwise resolve rdar://76252171 * Fix test linking to heading that doesn't exist * Update expression that was very slow to type check * Fix warning about mutating a captured sendable value * Remove outdated comment about adding more test assertions * Update test for old link resolver implementation
…le#582) * Add successfully resolved external references to reference index rdar://108974747 * Undo accidental whitespace change Co-authored-by: Ethan Kusters <ekusters@apple.com>
* Prefer non-symbols in general documentation links rdar://109583745 * Elaborate comment about filtering symbol and non-symbol collisions. Also, add test where symbol and non-symbol have same path.
`mode_t` is a non-portable extension to C (POSIX). Introduce a new typealias `ModeType` that represents the underlying type that is used. Provide an alternate definition for the default mode on Windows as it does not have non-user permissions on a file but rather relies on proper ACLing.
A new `@TitleHeading` metadata directive for customizing the text of a page-title heading (also known as an eyebrow or kick).
`@TitleHeading` accepts an unnamed parameter containing containing the page-title’s heading text.
@metadata {
@TitleHeading("Release Notes")
}
This feature has been pitched on the forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#titleheading-10
rdar://110662981
) When converting a directory that only has Markdown files in it, it feels redundant to rename the directory to have a `.docc` extension just for the sake of rendering those files. It would be great if DocC supported converting any directory regardless of its extension out of the box. This new behavior is conditional on the newly introduced `--allow-arbitrary-catalog-directories` flag.
…le#627) Allows clients to access and modify the destination URL for an `ExternalLocationReference`. rdar://110803672
This mirrors the Linux and Android paths and excludes this test on Windows. With this change (and 1 workaround), we can fully execute the test suite (though not yet pass it completely).
rdar://110182993
Ensure that we release the open handles before attempting to clean up the temporary directory. This repairs the execution of 11 tests on Windows, bringing us to a 95% pass rate (excluding `LogHandleTests`).
rdar://110683602
`FileHandle` transacts in `HANDLE`s on Windows rather than file descriptors. This makes it impossible to replace the end point of the pipe after it has been created as the conversion from a HANDLE to a file descriptor transfers ownership and as such the FileHandle does not work with file descriptors at all. Replicating that behaviour here would detach the `FileHandle` associated with the `Pipe` and thus cannot be done inline.
This ensures that any gathered diagnostics are printed before exiting. rdar://110782381
Co-authored-by: Ethan Kusters <ekusters@apple.com>
…pple#642) * Fix false-positive warning for curated symbols with special characters rdar://111227479 * Remove redundant symbol index modification
) Ensure that we close the LMDB environment on the exit from `finalize(_:_:_:)` method. This is important for platforms which do not permit alteration of directories with open references. Having the environment be closed after finalization enables the generated index to be moved into the final destination on Windows.
Co-authored-by: Ethan Kusters <ekusters@apple.com>
* Make visitLineBreak return new line instead of space * Update test case for more human-readable
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.