> Why was that so hard? Why are the models here separate from the ones in the right click menu? Too many questions.
The very screenshot above this paragraph actually answers this, in what admittedly might be an uncharacteristically clear UI: "Siri and Safari will always run translations online."
Reading and understanding the docs and reference material has always been part of the work.
Aside from the commentary it read like an advertisement for how great the swift/macos translation APIs are. PEBCAK
So, you reach for AI and it works really well. So you start reaching for that more and more...
Like, how can it run a command that has an `async` main despite the fact that you didn't extend the async version of command?? That should've been an error (e.g. "bro, you cannot have an async main in this class, you need the Async version of this class which is called AsyncWhatever").
Not awaiting on an async function should be at least a warning. Another frustrating lack of feedback: it just lets you run it and nothing happens.
The version thing: it should show all possible variants in the enum, even the ones you should not be able to use, and then when you try using it, show an error saying "you need to change the version of this file to at least blah to use this". Why can't the Swift LSP do that? Apple has a trillion dollars, they can afford polishing their stuff.
The author is used to Rust, which would've made it very clear what was wrong in all cases.
Swift, being as modern as Rust, should be doing better than that. Languages that fail to give you proper error messages and warnings are just not worth it: just one of these "wtf is going on?" moments can cost you hours. Just use a better language if you can.
This is the same issue with libraries. They should limit how you build your code. This is why I hate frameworks as a whole. They don't add anything, just abstract and limit.
This page was much simpler 22 years ago (I don't remember this HSSF stuff, whatever that is), but it still looks familiar. Basically everything I needed to do had examples in there. I remember thinking that the authors cared about the users of the library (although the Javadoc seems a little bare.. but I am not sure I needed the Javadoc much).
If I ever create an OSS library, I would certainly also create a "Busy Developers' Guide".
I've always loved Microsoft's API Browser for this reason: https://learn.microsoft.com/en-us/dotnet/api/system.net.netw...
https://developer.apple.com/documentation/translation/transl...
I don’t regularly develop in swift, but when I have, I’ve been confused by the docs because they are so clearly auto generated (not LLM, just from the code) and sparse. Listing out constants is next to useless when they are confusingly named and have no description of what they mean or how the affect things.
In a nutshell, which type of documentation we need depends on the goal we have. Any API missing one of the kinds of documentation will feel like it is missing something. Once I read about it, I've been noticing how the documentation I like tends to have all these aspects covered.
https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...
API design isn't just about functionality. it is about discoverability and if your right-click menu uses different models than your API and your error messages don't explain why, you are just creating friction for no reason.
Sometimes the "proper" solution isn't worth the super complicated maze.
The general idea is a bit like uv if I have understood uv correctly. Basically you do your imports normally and add a comment next to them that tells where the imports should be found. Then instead of running your project through swift directly you run it through swift-sh (or `swift sh`, swift will find the `swift-sh` binary automatically, just like git does for plugins). swift-sh will download and compile the dependencies, then add the proper options to swift so it will know where to find them.
It is even possible to add a regular shebang to swift-sh at the beginning of the file, chmod +x it, and just run it like a regular script!
Or use swift-sh to compile it.
(And installing swift-sh itself is as easy as `brew install xcode-actions/tap/swift-sh`.)
Edit: Come to think of it, both are made by Google :')
When working on my own projects I've found a good rule of thumb to be that if you are being told to use something low level and unintuitive like a semaphore in Swift when doing something that ought to be easy, you are probably either reading a stackoverflow answer from an objective-c developer or in the middle of a LLM session that's gone sideways. Low level libraries might need those things, they are approximately never right for application code. Just throw it out and start over (as you did), saves on sanity.
That's how modern software industry feels like.
Apple’s documentation is often very poor, and I will note that Swift Packages (especially CLIs) doesn’t always feel great. As another commenter noted, anything other than Xcode feels like fighting an uphill battle.
But many of your frustrations could be solved by checking not API docs, but just the Swift language guide. You seem perturbed, for example, that the Package initializer expects ordered arguments. It is a basic part of Swift’s design that arguments are always ordered and exclusively are either named or unnamed (never optionally both).
The ghost’s use of semaphores with async/await is a massive red flag in terms of mixing two asynchronous frameworks (Concurrency and GCD). I’d not be surprised if it worked, but that’s really against the grain in terms of how either framework were designed. This is the shortfall of relying on bottled ghosts to learn new tools. I know from experience that the documentation on Concurrency (async/await) is pretty good, and lays out a clear rationale for how it’s intended to be used, but that is a huge piece of documentation and it’s a big hill to climb when all you’re building is a small tool. This is the risk we run when asking AI for help when it itself is ignorant of the actual intended use of the apis and is only trained on the output of developers. Here it’s easy to see that it was faced with a problem of synchronous access to an async function and reached for a common solution (semaphore), despite the fact that semaphores are part of a 10 year old framework, and the async/await keywords are only 2-3 years old!
Anyway, the article reminded me of the challenges of learning a new (programming) language. There’s more to it than just following tutorials and blindly directing AI. I know the feeling, having to currently learn c# at the moment. I can write simple functions and follow the syntax, but I can’t intuitively understand what’s happening like I can with Swift. Is that because Swift is better than C#? Not really- it’s just that I’m fluent in one but not the other. Ironically I guess you probably get this already from learning Mandarin, but you’ve not written an article about how frustrating it is that it inexplicably insists on using tones to express meaning, when English is fine without it(!).
I’m sorry you had a bad experience with Swift. I do genuinely think it’s a great language to write, and the open source Swift Evolution team are great. They are continually pushing for more openness and more cross platform compatibility, and I do like the way that the core of the language is strongly opinionated in a way that makes it clear what’s happening if you do understand the syntax. What’s hard is then the application of Apple’s APIs which are wildly inconsistent and often incomplete. Some are maintained while others are still wrappers for 15 year old objective C that have no concept of modern Swift paradigms. That said, I’d still encourage you to persevere with Swift. Once you get past those rough edges of stdio and UI and get into the heart of a Package, I would expect most of these complaints to disappear!
> ... I found mysekf launching TextEdit just to do that
I hope everyone else enjoys it!
on the other hand, I appreciated knowing that it was actually written by a frustrated human, and not sanitized by the Ghost.
LLMs are good at style transfer in fully general sense, they can introduce typos and bad grammar just as easily as it can correct them.
I did not knew this.
It's clearly not enjoyable for them so why doesn't the author pivot to something else and stop doing things they hate? It's weird