[docs] Fix non-public entry docs. Various improvements to PTB docs. (#25913)

## Description 

- Updated the docs around `entry` functions.
- Fixed missing sections for:
  - Move calls
  - TxContext
  - Publish
  - Upgrade 
  
## Test plan 

- 👀 
---

## Release notes

Check each box that your changes affect. If none of the boxes relate to
your changes, release notes aren't required.

For each box you select, include information after the relevant heading
that describes the impact of your changes that a user might notice and
any actions they must take to implement updates.

- [ ] Protocol: 
- [ ] Nodes (Validators and Full nodes): 
- [ ] gRPC:
- [ ] JSON-RPC: 
- [ ] GraphQL: 
- [ ] CLI: 
- [ ] Rust SDK:
- [ ] Indexing Framework:

---------

Co-authored-by: Adam Welc <adam@mystenlabs.com>
Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com>
Co-authored-by: Damir Shamanaev <damirka.ru@gmail.com>

Author: 4 people

docs/content/concepts/sui-move-concepts.mdx

@@ -64,6 +64,10 @@ Make your function private (don't add the `public` visibility keyword) and mark
 
 In addition to this Sui-specific use case, there are other rules and restrictions for `entry` functions:
 
-- `entry` functions can only return types with the `drop` ability.
+- Non-public `entry` functions (private or `public(package)`) have restrictions on arguments that are entangled with hot potato values in a PTB. See [Non-public entry function restrictions](/guides/developer/transactions/ptbs/prog-txn-blocks#non-public-entry-function-restrictions) for details.
 
-- `entry` functions can only take objects as inputs if they weren't used as inputs in any non-`entry` functions in the same PTB.
+:::info
+
+Note that while previously `entry` functions had additional restrictions on their signatures (their types for parameters and return values), this is no longer the case. `entry` functions can have the same arguments or return values as a `public` function in a PTB.
+
+:::

docs/content/guides/developer/dev-cheat-sheet.mdx

@@ -30,7 +30,7 @@ Quick reference on best practices for Sui Network developers.
 - Packages are immutable, so any published package can be called forever. Use [object versioning](/guides/developer/packages/upgrade.mdx#versioned-shared-objects) to prevent older versions from being called.
 - If you upgrade a package `P1` to `P2`, other packages and clients that depend on `P1` will continue using `P1`. They do not auto-update to `P2`. Both dependent packages and client code must be explicitly updated to point at `P2`.
 - Packages that expect to be extended by dependent packages can avoid breaking their extensions with each upgrade by providing a standard (unchanging) interface that all versions conform to. See the [message sending](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move) across a bridge example from Wormhole. Extension packages that produce outbound messages can use [`prepare_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L68-L90) from any version of the Wormhole package to produce a [`MessageTicket`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L52-L66) while client code that sends the message must pass that `MessageTicket` into [`publish_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L92-L152) in the latest version of the package.
-  - `public` function signatures cannot be deleted or changed, but `public(friend)` functions can. Use `public(friend)` or private visibility liberally unless you are exposing library functions that will live forever.
+  - `public` function signatures cannot be deleted or changed, but `public(package)` functions can. Use `public(package)` or private visibility liberally unless you are exposing library functions that will live forever.
   - It is not possible to delete `struct` types, change their definition or add new [abilities](https://move-book.com/reference/abilities) via an upgrade. Introduce new types carefully as they will live forever.
 
 ### Testing

docs/content/guides/developer/objects/object-ownership/immutable.mdx

@@ -37,9 +37,9 @@ This function creates a new `ColorObject` and immediately makes it immutable bef
 
 ## When to use immutable objects
 
-After an object becomes immutable, the rules of who can use this object in Sui Move calls change:
+After an object becomes immutable, the rules of who can use this object in Move calls change:
 
-1. You can only pass an immutable object as a read-only, immutable reference to Sui Move entry functions as `&T`.
+1. You can only pass an immutable object as a read-only, immutable reference to Move functions as `&T`.
 
 2. All network participants can access immutable objects.
 
@@ -166,4 +166,4 @@ public fun update(
 }
 ```
 
-The function fails because the `ColorObject` is immutable.
+The function fails because the `ColorObject` is immutable.

docs/content/guides/developer/transactions/ptbs/inputs-and-results.mdx

@@ -8,7 +8,7 @@ Programmable transaction blocks (PTBs) operate on inputs and produce results. In
 
 ## Inputs 
 
-Input arguments to a PTB are broadly categorized as either objects or pure values. The direct implementation of these arguments is often obscured by transaction builders or SDKs. Each `Input` is either an object, `Input::Object(ObjectArg)`, which contains the necessary metadata to specify the object being used, or a pure value, `Input::Pure(PureArg)`, which contains the bytes of the value.
+Input arguments to a PTB are broadly categorized as either objects or pure values. The direct implementation of these arguments is often obscured by transaction builders or SDKs. Each `Input` is either an object, `CallArg::Object(ObjectArg)`, which contains the necessary metadata to specify the object being used, or a pure value, `CallArg::Pure(Vec<u8>)`, which contains the BCS bytes of the value.
 
 For object inputs, the metadata needed differs depending on the type of [ownership of the object](/guides/developer/objects/object-ownership). The data for the `ObjectArg` enum follows:
 
@@ -32,19 +32,19 @@ For pure inputs, the only data provided is the [BCS](https://github.com/MystenLa
 
 For vectors and options, `T` must be a valid pure input type. This rule applies recursively.
 
-Bytes are not validated until the type is specified in a command, for example in `MoveCall` or `MakeMoveVec`. This means that a given pure input could be used to instantiate Move values of several types.
+Bytes are not validated until a command specifies the expected type, for example in `MoveCall` or `MakeMoveVec`. Each distinct type creates a separate typed copy of the bytes, so the same pure input can be used at multiple types as long as the bytes are valid for each. Each typed copy is treated as its own input, so mutations affect only that type's value.
 
 ## Results
 
 Each transaction command produces an array of values. The array can be empty. The type of the value can be any arbitrary Move type, so unlike inputs, the values are not limited to objects or pure values. The number of results generated and their types are specific to each transaction command:
 
-- `MoveCall`: The number of results and their types are determined by the Move function being called. Move functions that return references are not supported at this time.
+- `MoveCall`: The number of results and their types are determined by the Move function being called. Move calls cannot return references (`&T` or `&mut T`); this restriction will be lifted in the future.
 
 - `SplitCoins`: Produces one or more coins from a single coin. The type of each coin is `sui::coin::Coin<T>` where the specific coin type `T` matches the coin being split.
 
-- `Publish`: Returns the upgrade capability `sui::package::UpgradeCap` for the newly published package.
+- `Publish`: Returns a single `sui::package::UpgradeCap`. Module bytes and dependency IDs are embedded in the command structure; they are not `Argument` values. After the package is staged, `init` functions run for each module in order.
 
-- `Upgrade`: Returns the upgrade receipt `sui::package::UpgradeReceipt` for the upgraded package.
+- `Upgrade`: Takes exactly one `Argument`: a `sui::package::UpgradeTicket` (by value). Returns a single `sui::package::UpgradeReceipt`. Module bytes and dependency IDs are embedded in the command, not supplied as `Argument` values. Does not call `init` functions.
 
 - `TransferObjects` and `MergeCoins` produce an empty result vector.
 
@@ -104,7 +104,7 @@ const hero = tx.moveCall({
    typeArguments: [],
 });
 
-//According to Move function new_sword, this moveCall will return an Object of Type Hero
+// According to Move function new_sword, this moveCall will return an Object of Type Sword
 const sword = tx.moveCall({
    target: `0x123::hero::new_sword`,
    arguments: [tx.pure.u64(10)],