I was experimenting with Actor:SwapNextInventory(), and came across a weird glitch. The function description in the documentation says: From what I've seen, this is not the case. Instead, the "next MovableObject" disappears and the "one not currently carried" is added to the back end of your inventory. The "next MovableObject" weapon then disappears from you inventory .

Furthermore, the "not currently carried" weapon does not get added to your inventory until you switch to it. So, it will sit there on the ground until you switch to it, when it then magically appears in your hands.

How the fudge are we supposed to use this function properly?

By waiting for data to not halfass lua implementation? This may/may not take another year.

Or atleast bring it up to the point where hacks can do enough to work right.

No. What it does is, it takes the next carried object (it omits the currently held one), removes it, and shovels a new object into the back of the inventory. The description should read:

"Swaps the next MovableObject carried by this Actor with one not currently carried and puts it into the into the back of the inventory of this."

In conjunction with the Inventory() func I found, it cycles through the inventory without changing the contents.

It also doesn't need an existing MO object, it takes a reference that you get from CreateHDFirearm or the like. If you spawn the MO object, then yes, it will appear in your hands only when you cycle to it, because objects in inventory are normally removed from the MovableManager, while keeping the references.
I suppose you could use this to make all of the actor's inventory actually appear on him. Would be fun.