Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,19 @@ public struct RenderContentMetadata: Equatable, Codable {
public var abstract: [RenderInlineContent]?
/// An optional identifier for the device frame that should wrap this element.
public var deviceFrame: String?

/// Creates a new metadata value for a content element.
/// - Parameters:
/// - anchor: The named anchor of the content element.
/// - title: The customized title for the content element.
/// - abstract: The customized abstract for the content element.
/// - deviceFrame: The identifier for the device frame that should wrap the content element.
public init(anchor: String? = nil, title: String? = nil, abstract: [RenderInlineContent]? = nil, deviceFrame: String? = nil) {
self.anchor = anchor
self.title = title
self.abstract = abstract
self.deviceFrame = deviceFrame
}
}

extension RenderContentMetadata {
Expand Down
27 changes: 27 additions & 0 deletions Tests/SwiftDocCTests/PublicAPI/PublicAPITests.swift
Copy link
Contributor

@d-ronnqvist d-ronnqvist Nov 7, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's fine to have this test but I don't find it important to test that initializers set the properties of a structure because the compiler will already enforce that the initializer assigns a value to every property.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking about this unit test some more, I've decided to rename & move the Swift file and test class to something more generic. I think this test file could be generally useful in the future for testing public access to various DocC API.

See: c587ac9

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think running a test is a good mechanism for verifying that a piece of API is public. To my knowledge we don't do that for any other public API.

I personally don't think that having this test will meaningfully help us remember to make other future API in other types public and I think that the odds that this test protects us against unintentionally removing this API or changing it to a lower access level is abysmal.

I don't think it's harmful to have this test but I think the value it adds is fairly close to zero.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify; I'm not requesting that we remove this test, but I feel that the discussion around adding it has already cost more time and productivity that we'll ever regain from having this test.

Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
/*
This source file is part of the Swift.org open source project

Copyright (c) 2025 Apple Inc. and the Swift project authors
Licensed under Apache License v2.0 with Runtime Library Exception

See https://swift.org/LICENSE.txt for license information
See https://swift.org/CONTRIBUTORS.txt for Swift project authors
*/

// Import SwiftDocC without the @testable annotation, so we can test
// whether various API are actually public.
import SwiftDocC

import XCTest

class PublicAPITests: XCTestCase {

func testPublicRenderContentMetadataInitializer() throws {
let _ = RenderContentMetadata(
anchor: "anchor",
title: "title",
abstract: [],
deviceFrame: "device frame"
)
}
}