# Listing stored properties of a type

**URL:** <https://forums.swift.org/t/listing-stored-properties-of-a-type/68351>\
**Category:** Swift-DocC\
**Tags:** symbolgraphgen\
**Created:** [November 8, 2023, 11:48pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351 "2023-11-08T23:48:52Z")\
**Posts on this page:** 20\
**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:** [November 8, 2023, 11:48pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/1 "2023-11-08T23:48:52Z")

</div>

something that’s been on my wishlist for a while has been the ability to categorize the stored properties of a type separately from the computed properties. it is currently very difficult to sort through _all_ of the instance properties from the generated documentation to understand what a type’s actual representation is.

i did some investigation into this idea today, and discovered that lib/SymbolGraphGen currently classifies _all_ instance properties as stored properties ([`vp`](https://github.com/apple/swift/blob/main/docs/ABI/Mangling.rst#entities)).

it is also not possible to deduce this from the presence of accessors (`{ get }`, `{ get set }`, etc.) in the emitted symbol declaration, since those also appear for stored `public private(set)` properties.

what would it take for lib/SymbolGraphGen to emit this information?

cc @QuietMisdreavus

---

<div class="post-metadata">

**Author:** ![jrose](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jrose/32/408_2.png) [@jrose](https://forums.swift.org/u/jrose)\
**Post date:** [November 9, 2023, 1:01am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/2 "2023-11-09T01:01:03Z")

</div>

Note that it is very much by design that Swift-the-language does not distinguish stored and computed properties by default. Changing representations is supposed to be a source-compatible change.

---

<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:** [November 9, 2023, 1:04am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/3 "2023-11-09T01:04:40Z")

</div>

> [@jrose](#):
>
> Note that it is very much by design that Swift-the-language does not distinguish stored and computed properties by default.

right, but when you have a type with a large population of instance properties, it becomes a problem when “important” properties get lost in a long list of computed properties. this is really just about the readability of the generated docs.

> [@jrose](#):
>
> Changing representations is supposed to be a source-compatible change.

nothing about surfacing “storeness” in generated documentation is going to have any impact on source compatibility. if a stored property becomes a computed property (or vice versa), the only observable change in the documentation is the symbol would move to a different heading on the same page.

---

<div class="post-metadata">

**Author:** ![AlexanderM](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/alexanderm/32/9781_2.png) [@AlexanderM](https://forums.swift.org/u/AlexanderM)\
**Post date:** [November 9, 2023, 1:29am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/4 "2023-11-09T01:29:24Z")

</div>

> [@taylorswift](#):
>
> it becomes a problem when “important” properties get lost in a long list of computed properties.

Hmmm, I think then it would be better to organize the properties into headings regarding which ones are "important" or not.

There could be important computed properties, and unimportant stored ones. I'm not sure if "is stored or not" would be a useful distinction from a documentation perspective. And that matches the OO philosophy on the matter, that storage is an implementation detail which shouldn't be exposed.

Do you have any examples that illustrate the issue?

---

<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:** [November 9, 2023, 1:45am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/5 "2023-11-09T01:45:27Z")

</div>

> [@AlexanderM](#):
>
> And that matches the OO philosophy on the matter, that storage is an implementation detail which shouldn't be exposed.

right, i think this is an important difference between class-heavy styles of programming and struct-heavy styles.

> [@AlexanderM](#):
>
> Do you have any examples that illustrate the issue?

here’s an small example:

> <https://github.com/tayloraswift/swift-unidoc/blob/0.3.14/Sources/SemanticVersions/PatchVersion.Components.swift#L4>

from looking at the type’s source code, you can see it is just a glorified `(UInt16, UInt16, UInt16)` tuple.

but if you browse its [documentation](https://swiftinit.org/docs/swift-unidoc/semanticversions/patchversion/components), it actually has five instance properties.

- `var description: String`
- `var major: UInt16`
- `var minor: UInt16`
- `var patch: UInt16`
- `var rawValue: Int64`

but the `description` and the `rawValue` are not integral to the type, they are hooks for protocol conformances. as the type matures, it would likely gain many more such “conformance” or “convenience” properties, and the only reason it doesn’t have more already is because i am consciously trying to avoid this problem by limiting the amount of API this type exposes.

---

<div class="post-metadata">

**Author:** ![tera](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tera/32/38201_2.png) [@tera](https://forums.swift.org/u/tera)\
**Post date:** [November 9, 2023, 4:31am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/6 "2023-11-09T04:31:58Z")

</div>

Could it be organised in sections?

- `var major: UInt16`
- `var minor: UInt16`
- `var patch: UInt16`

protocol CustomStringConvertible:

- `var description: String`

protocol RawRepresentable:

- `var rawValue: Int64`

---

<div class="post-metadata">

**Author:** ![wadetregaskis](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/wadetregaskis/32/8494_2.png) [@wadetregaskis](https://forums.swift.org/u/wadetregaskis)\
**Post date:** [November 9, 2023, 6:53am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/7 "2023-11-09T06:53:12Z")

</div>

Somewhat related, I needed to know the actual layout of various structures earlier this evening - e.g. `UnsafeMutableBufferPointer` - and I ultimately had to dig up some gyb templates buried deep in the Swift stdlib sources (and then read _very_ carefully to ensure I'd found all the stored properties, since their declarations can appear practically anywhere in the file). If you don't know to specifically go to GitHub and specifically search Apple's "Swift" repo _and_ to fiddle with the language settings to get it to actually surface those template files, you'll never find them. Search engines work really hard to not show GitHub source code results.

If they'd been simply listed in the documentation, even if just in some appendix or footnote, I'd have been much happier.

Note that in this case the order is important, too. I need to know the _full_ layout in order to map that to registers and the like.

---

<div class="post-metadata">

**Author:** ![tera](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tera/32/38201_2.png) [@tera](https://forums.swift.org/u/tera)\
**Post date:** [November 9, 2023, 11:34am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/8 "2023-11-09T11:34:08Z")

</div>

> [@wadetregaskis](#):
>
> Note that in this case the order is important, too. I need to know the _full_ layout in order to map that to registers and the like.

Can you use Mirror for that? It doesn't return everything but you could figure quite a few things about structs layout:

```swift
let x = UnsafeMutableBufferPointer<Int>(start: nil, count: 10)
let m = Mirror(reflecting: x)
print(m.subjectType) // UnsafeMutableBufferPointer<Int>
print(m.displayStyle!) // struct
print(m.children.count) // 2
for child in m.children {
    print(child.label!) // _position, count
    print(child.value) // nil, 10
}
print("offset of _position:", MemoryLayout<UnsafeMutableBufferPointer<Int>>.offset(of: \._position)!)
// 🛑 Error: '_position' is inaccessible due to 'internal' protection level
print("offset of count:", MemoryLayout<UnsafeMutableBufferPointer<Int>>.offset(of: \.count)!) // 8

```

---

<div class="post-metadata">

**Author:** ![scanon](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/scanon/32/2445_2.png) [@scanon](https://forums.swift.org/u/scanon)\
**Post date:** [November 9, 2023, 1:30pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/9 "2023-11-09T13:30:56Z")

</div>

> [@jrose](#):
>
> Note that it is very much by design that Swift-the-language does not distinguish stored and computed properties by default. Changing representations is supposed to be a source-compatible change.

I think that it would make some sense to document the stored properties for _frozen_ types specifically.

---

<div class="post-metadata">

**Author:** ![jrose](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jrose/32/408_2.png) [@jrose](https://forums.swift.org/u/jrose)\
**Post date:** [November 9, 2023, 2:36pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/10 "2023-11-09T14:36:15Z")

</div>

Even frozen types don’t necessarily make all of their stored properties _public,_ so having a “stored properties” section there could still seem like it’s providing more information than it really is.

---

<div class="post-metadata">

**Author:** ![tera](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tera/32/38201_2.png) [@tera](https://forums.swift.org/u/tera)\
**Post date:** [November 9, 2023, 2:46pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/11 "2023-11-09T14:46:05Z")

</div>

What are exact guarantees about frozen types? Could this change happen or not?

```swift
// old version
@frozen public struct S {
    var x: Int
}

// new version
@frozen public struct S {
    private var y: Int
    var x: Int {
        get { y &- 1 }
        set { y = newValue &+ 1 }
    }
}

```

---

<div class="post-metadata">

**Author:** ![scanon](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/scanon/32/2445_2.png) [@scanon](https://forums.swift.org/u/scanon)\
**Post date:** [November 9, 2023, 3:02pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/12 "2023-11-09T15:02:34Z")

</div>

That change is ABI breaking for a frozen type (but admittedly in a weird and subtle way).

---

<div class="post-metadata">

**Author:** ![tera](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/tera/32/38201_2.png) [@tera](https://forums.swift.org/u/tera)\
**Post date:** [November 9, 2023, 3:03pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/13 "2023-11-09T15:03:38Z")

</div>

And this one?

```swift
// new version
@frozen public struct S {
    private var y: Int
    var x: Int {
        get { y }
        set { y = newValue }
    }
}

```

---

<div class="post-metadata">

**Author:** ![wadetregaskis](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/wadetregaskis/32/8494_2.png) [@wadetregaskis](https://forums.swift.org/u/wadetregaskis)\
**Post date:** [November 9, 2023, 4:44pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/14 "2023-11-09T16:44:08Z")

</div>

> [@tera](#):
>
> Can you use Mirror for that?

Perhaps, but it's a bit of a pain to have to write the boilerplate code for it, versus just looking at some simple documentation.

I did think about doing that, but I figured it's still easier to dig up the source on GitHub. At least, where that's available.

---

<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:** [November 9, 2023, 5:31pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/15 "2023-11-09T17:31:35Z")

</div>

> [@tera](#):
>
> Could it be organised in sections?
> 
> - `var major: UInt16`
> - `var minor: UInt16`
> - `var patch: UInt16`
> 
> protocol CustomStringConvertible:
> 
> - `var description: String`
> 
> protocol RawRepresentable:
> 
> - `var rawValue: Int64`

it is a basic tradeoff when going from class inheritance to protocol-oriented patterns that you lose the ability to reverse-map declarations to protocol conformances.

for example, a type might expose a `description` property that witnesses multiple protocol requirements, or might witness a conformance declared in a downstream module.

---

<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:** [November 14, 2023, 12:02am UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/16 "2023-11-14T00:02:41Z")

</div>

> [@taylorswift](#):
>
> here’s an small example:

i came across a somewhat more motivating example that doesn’t have anything to do with protocol conformances in the form of this datetime formatter type i have:

[`Timestamp.Components`](https://swiftinit.org/docs/swift-unidoc/unixtime/timestamp/components)

```swift
var day: Int32
var DD:String
var hh: String
var hour: Int32
var minute: Int32
var mm: String
var MM:String
var month: Int32
var second: Int32
var ss: String
var year: Int32
var yyyymmdd: String
var yyyymmddThhmmssZ: String

```

---

<div class="post-metadata">

**Author:** ![AlexanderM](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/alexanderm/32/9781_2.png) [@AlexanderM](https://forums.swift.org/u/AlexanderM)\
**Post date:** [December 17, 2023, 4:27pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/17 "2023-12-17T16:27:33Z")

</div>

Funny enough, I just ran into a case at work (in Ruby) where I had to optimize a class that represents a SemVer Version, which changed its layout.

I changed it from having 3 seperate fields for `major`/`minor`/`patch`, to a single bit-packed Integer. This allowed us to greatly speed up the `<` operator, which our app used _a lot_.

This is a perfect example of where decoupling internal storage from API is useful, regardless if you're doing traditional class-oriented OOP or not. If the docs put an emphasis on the stored properties, then the docs for `major`/`minor`/`patch` would have been de-emphasized, and the docs for this random `packedInt` would have been emphasized instead.

It would be better if `major`/`minor`/`public` fields were highlighted intentionally+explicitly as members of a section, rather than implicitly because they happened to be stored properties instead of computed.

---

<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:** [December 17, 2023, 4:59pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/18 "2023-12-17T16:59:03Z")

</div>

> [@AlexanderM](#):
>
> I changed it from having 3 seperate fields for `major`/`minor`/`patch`, to a single bit-packed Integer. This allowed us to greatly speed up the `<` operator, which our app used _a lot_.

ha, i had a [similar issue](https://forums.swift.org/t/awful-codegen-for-of-plain-old-data-type/68047) with an IP address type, except in my case it was the `==(_:_:)` operator.

> [@AlexanderM](#):
>
> It would be better if `major`/`minor`/`public` fields were highlighted intentionally+explicitly as members of a section, rather than implicitly because they happened to be stored properties instead of computed.

the thing is i don’t think the “Topics” system is mature enough where we can lean on that as a curation mechanism. my main issue with “Topics” lists is that you need to know the symbol hashes to create them, and the symbol hashes are just dreadful to work with, particularly if you’re not using XCode.

probably stored-ness is not the best heuristic to use here. but i think we still do need one.

---

<div class="post-metadata">

**Author:** ![AlexanderM](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/alexanderm/32/9781_2.png) [@AlexanderM](https://forums.swift.org/u/AlexanderM)\
**Post date:** [December 17, 2023, 5:32pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/19 "2023-12-17T17:32:07Z")

</div>

> [@taylorswift](#):
>
> probably stored-ness is not the best heuristic to use here.

Exactly, perhaps improving the DX of topics is the better direction here

---

<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:** [December 17, 2023, 5:43pm UTC](https://forums.swift.org/t/listing-stored-properties-of-a-type/68351/20 "2023-12-17T17:43:59Z")

</div>

yeah but that’s fundamentally an IDE/editor issue and any improvements there would have to come from the VSCode plugin side. it’s not apparent to me what documentation tooling can do here.
