Read the Fine Manual (RTFM)

RTFM

Read the Fine Manual... I started my coding career when this was the only abbrevation/acronym one needed to understand. I've read a lot of manuals. Typically learn something that way.

I'm suprised by the fact that I cannot seem to understand the Apple Swift Manual.

Even this Apple Forum Question went unAnswered.
How to read apple documentation?

Several of my favorite Swifty authors have touched on the topic... none seems to do the topic real justice.

Here is an example of what throws me... just one example:

The Apple Doc states:

Declaration

struct AxisMarks<Content> where Content : AxisMark

I truely don't know what to make of that... OK... we need some "content" for the marks - makes lots of sense - what type of content? Oh... we need content where it is an AxisMark type - so far so good.

I then look for the init() method and find quite a few... but weirdly NONE take an AxisMark type - that's strange and baffelling. But not really helpful to me.

So perhaps I do not understand what the phrase "
where Content : AxisMark" means. Anyone?

That is about as far as I get with this paticular investigation... I try googling and looking at example code for a real world example of usage. This effort becomes much more fruitfull. I found this blog about
WooCommerce App. Digging deep and into there GitHub files I find the usage:


.chartYAxis {

AxisMarks(position: .leading, values: .stride(by: yAxisStride)) { value in

AxisGridLine()

AxisValueLabel(yAxisLabel(for: value.as(Double.self) ?? 0))

}

}


Well that looks nothing like the code I was trying to craft for an AxisMarks on the Y-Axis of my Chart. When I parse this code... and it takes me a lot of effort...

I get the
position: .leading. Yeah, left adjusted text - been doing that for years.

The phrase "
values: .stride(by: yAxisStride)" while I have no idea what that is or what it means... in the big picture it seems I could defer knowing the details of that phrase and look up the symbol yAxisStride sometime later.

Then I see the "
{ value in ". OK... I've been coding SwiftUI long enough not to be thrown into fear-and-dread of - closures. Parsing that ... it is a trailing closure on AxisMarks(). I scratch my head on the term "value" is it coming in or out? Where does "value" come from... it's not outside this scope... confussion is clouding my head. I look at the Apple Docs for AxisMarks... absolutely no help!


[ Note -- later this week: This { value in syntax is "trailing closure parameter passing shorthand syntax. I finally found a great explaination on Paul Hudson's Hacking With Swift site.
Using closures as parameters when they accept parameters and How to use trailing closures and shorthand syntax.
I also learn that
AxisMarks has an initializer that matches our code.
It has a "content: @escaping (AxisValue) -> Content" Content is a Result Builder thingy, I think that's similar to a View Builder thingy. This defines an escaping closure with AxisValue as parameter and returning Content. ]


OK ... parsing on ... into the closure - we call AxisGridLine() with nothing - wonder what that does... seems rather defaultish, why have it if its just the default?

Moving on...
AxisValueLabel() Yeah... this is WHY I'm here... what the heck is this...

That is not a parameter name - what the heck kind of value type thingy is yAxisLabel(for:)? Looking back at Apple's Doc... no help here. So I go searching the code and find that it is a private function returning a String. OH... OK ignore that detail.

Whatever that function does - it gives a string to the AxisValueLabel().init() function inside our closure with the "value in" looping construct - is that right? I do expect we will have multiple string labels on the Y axis. So this closure thingy ... it should be a construct that does multiple Strings. Right?

[ Note -- later this week: This is not a looping construct - is it - No. But this trailing closure thingy - it should get called multiple times for a typical Y-Axis.
Remember that the AxisMarks has an array of values and that it passes the arrray into the closure.]

Now I go back to Apples Fine Manual... where does it say anything about init-ing the AxisValueLabel with a value ... that is a String. Damn there are lots of parameters in those init() lists. I keep seeing those parameters and FREEKING OUT... but in the real-world usage they don't pass them in ... weird - WHY/HOW? Examining very closely I see that only StrokeStyle is optional. Seems like the other parameters are required. But not in our real-world example. Confused! Take a break!

Coming back refreshed... I catch something I don't really understand. The docs states "init<Value>(..." in some instances, not all. Wow - there's that word Value again. This time it is capatilized like it is a Type. Oh and inside the dreaded angle brackets - meaning generics - which are a mind-blowing concept for some other day. How does this effect what I want to do... safe to ignore? Probablely - NOT.

Well this is a detailed thread of why I think the Apple Swift Docs needs a lot more example code embedded.

And with Charts - the docs need the graphics that are generated by the code. That type of example right about here ... that would be truely useful. Thanks Apple.

So a week later... I maybe have decoded this Swift syntax and the shorthand omitted code that is infered by the compiler. Enough to say I'm real close to understanding this one little piece of the Charts API. I think what could help me would be some type of index of idioms & syntax for the Swift language.

For example if I could some how look up " { value in " and find the common explaination: the beginning of a closure where the objects before the keyword "in" are the input parameters to the closure body (after "in" keyword). I went looking for an index in the Swift Language Reference - it is NOT there... guess that's too ol'-skool.

See Hacking with Swift attempt to teach reading the fine manual How to read Apple’s developer documentation

Get the most from our primary reference to UIKit and more.

How to use the Apple Developer Documentation - find the APIs you’re looking for https://www.youtube.com/watch?v=_HmNBrO5Mhc from Karin Prater

Maybe you can GROK the Apple "About the Language Reference - How to Read the Grammar" section.

I've been looking forward to Big Mountain Studio's Charts book - turns out he only did one chapter in the famous SwiftUI Views Mastery iOS16 - book update. There is so much more to learn.