Current docs say that Swap “works on symbols, labels, and graphical items.” However, it can also swap standalone references and values of symbols. Try this:
Select a symbol.
From another symbol, select only reference text.
Call Swap.
The first symbol and the text will exchange places.
This looks like bug to me. Or maybe word “labels” in the manual also means “symbol labels”? But they’re not called like that in KiCad. Also, it can swap references between two symbols, making the schematic confusing.
Also, the current docs say that Swap uses S hotkey, whereas it’s mapped to Alt+S in 9.0.2.
The docs should be better here. But since you’re speculating on the meaning of words, I’ll clarify the author’s intent a bit The docs generally lump text in with graphical objects. I don’t think I was thinking about symbol fields at all, but fields act like text even though they’re not purely graphical (reference designators have meaning, for example). Sheet fields are the same. Also, the “works on” list wasn’t meant to be an exclusive list, either, though it certainly reads as one right now. Swap also works on a number of other things that you may or may not want to swap, like NC markers and junction dots.
I would also argue that while the docs should certainly accurately describe KiCad behavior, it’s not necessarily a bug in KiCad if they don’t match. It could very easily be a docs bug (like this is).
Anyway I’ve clarified the language a bit. Thanks for the feedback.
Also fixed. In the future if you can report errors like this as bugs on gitlab (in the docs area) it’s appreciated. I care a lot about making sure these details are correct, but I check the forums very sporadically and things like this will get missed if they aren’t seen by me or someone else editing the docs.
Thanks for updating the docs. However, allow me to rephrase my question: Swap currently allows to swap object of different types, such as symbols with text or symbol fields with labels. That can easily introduce critical schematic errors, and I cannot fathom when could that be useful. That still looks like a bug to me, but I asked here to be sure.
I don’t think there is a bug, or behavior that should change, here, to be honest. Some of those combinations I can’t think of use cases for, but others I can imagine situations where they are useful.
For example: power symbols (VDD, GND) are a type of symbol. It makes sense in some situations to swap those symbols with labels and/or and NC markers.
Another example: a symbol can be used as a graphical marker in the schematic. Think of a logo for your company, a CC-BY-SA license logo, etc. You might also have some text for a link to your project repository, or a license explainer, etc. I can imagine wanting to swap these positions.
It seems difficult and not helpful to draw the line between useful combinations and not useful combinations.
KiCad generally takes the position that it shouldn’t go out of its way to prevent a user from doing something even if that something isn’t obviously useful or is potentially harmful. There are many potentially harmful tools in KiCad’s toolbox - you can do similar damage to your schematic with the move tool and an unwanted selection, no? KiCad expects you to be paying attention when you use a tool, run ERC, etc.
The docs generally lump text in with graphical objects. I don’t think I was thinking about symbol fields at all, but fields act like text even though they’re not purely graphical (reference designators have meaning, for example). Sheet fields are the same. Also, the “works on” list wasn’t meant to be an exclusive list, either, though it certainly reads as one right now. Swap also works on a number of other things that you may or may not want to swap, like NC markers and junction dots.