Begin SystemPacketBuffer.h cleanup (#4096)

* Begin SystemPacketBuffer.h cleanup

#### Problem

Code should use `PacketBufferHandle` rather than `PacketBuffer *`.
Some existing methods should be removed or made private so that code
does not have unnecessary access to the raw pointer.

#### Summary of Changes

- Consolidated PacketBuffer and PacketBufferHeader method descriptions
  into the header; clarified which are in transition.
- Most uses of Next(), which returns a raw pointer, only checked
  existence; added PacketBuffer::HasChainedBuffer() to replace these.
- Removed DetachTail_ForNow(), as it has no remaining callers.
- Converted TestSystemPacketBuffer to friended class, so that it can
  continue to use and test private methods. (Refactoring to focus on the
  PacketBufferHandle interface will follow.)

Part of issue #2707 - Figure out a way to express PacketBuffer ownership in the type system

* Fix Doxygen

* Fix Doxygen ONCE AND FOR ALL

* Fix description

* Description proofreading

src/ble/BLEEndPoint.cpp

@@ -662,11 +662,11 @@ BLE_ERROR BLEEndPoint::Send(PacketBufferHandle data)
 
     // Ensure outgoing message fits in a single contiguous PacketBuffer, as currently required by the
     // message fragmentation and reassembly engine.
-    if (data->Next() != nullptr)
+    if (data->HasChainedBuffer())
     {
         data->CompactHead();
 
-        if (data->Next() != nullptr)
+        if (data->HasChainedBuffer())
         {
             err = BLE_ERROR_OUTBOUND_MESSAGE_TOO_BIG;
             ExitNow();
@@ -1056,7 +1056,6 @@ BLE_ERROR BLEEndPoint::DriveSending()
 #if CHIP_ENABLE_CHIPOBLE_TEST
         mBtpEngineTest.DoTxTiming(sentBuf, BTP_TX_DONE);
 #endif // CHIP_ENABLE_CHIPOBLE_TEST
-        mBtpEngine.ClearTxPacket();
 
         if (!mSendQueue.IsNull())
         {
@@ -1420,7 +1419,6 @@ BLE_ERROR BLEEndPoint::Receive(PacketBufferHandle data)
     {
         // Take ownership of message PacketBuffer
         System::PacketBufferHandle full_packet = mBtpEngine.TakeRxPacket();
-        mBtpEngine.ClearRxPacket();
 
         ChipLogDebugBleEndPoint(Ble, "reassembled whole msg, len = %d", full_packet->DataLength());
 

src/ble/BtpEngine.cpp

@@ -357,7 +357,7 @@ BLE_ERROR BtpEngine::HandleCharacteristicReceived(System::PacketBufferHandle dat
 
         // For now, limit BtpEngine message size to max length of 1 pbuf, as we do for chip messages sent via IP.
         // TODO add support for BtpEngine messages longer than 1 pbuf
-        VerifyOrExit(mRxBuf->Next() == nullptr, err = BLE_ERROR_RECEIVED_MESSAGE_TOO_BIG);
+        VerifyOrExit(!mRxBuf->HasChainedBuffer(), err = BLE_ERROR_RECEIVED_MESSAGE_TOO_BIG);
     }
     else
     {
@@ -417,13 +417,13 @@ BLE_ERROR BtpEngine::HandleCharacteristicReceived(System::PacketBufferHandle dat
     return err;
 }
 
-void BtpEngine::ClearRxPacket()
+PacketBufferHandle BtpEngine::TakeRxPacket()
 {
     if (mRxState == kState_Complete)
     {
         mRxState = kState_Idle;
     }
-    mRxBuf = nullptr;
+    return std::move(mRxBuf);
 }
 
 // Calling convention:
@@ -570,13 +570,13 @@ bool BtpEngine::HandleCharacteristicSend(System::PacketBufferHandle data, bool s
     return true;
 }
 
-void BtpEngine::ClearTxPacket()
+PacketBufferHandle BtpEngine::TakeTxPacket()
 {
     if (mTxState == kState_Complete)
     {
         mTxState = kState_Idle;
     }
-    mTxBuf = nullptr;
+    return std::move(mTxBuf);
 }
 
 void BtpEngine::LogState() const

src/ble/BtpEngine.h

@@ -139,12 +139,12 @@ class BtpEngine
     bool HandleCharacteristicSend(System::PacketBufferHandle data, bool send_ack);
     BLE_ERROR EncodeStandAloneAck(const PacketBufferHandle & data);
 
-    void ClearRxPacket();
-    PacketBufferHandle TakeRxPacket() { return std::move(mRxBuf); }
+    PacketBufferHandle TakeRxPacket();
     PacketBufferHandle BorrowRxPacket() { return mRxBuf.Retain(); }
-    void ClearTxPacket();
-    PacketBufferHandle TakeTxPacket() { return std::move(mTxBuf); }
+    void ClearRxPacket() { (void) TakeRxPacket(); }
+    PacketBufferHandle TakeTxPacket();
     PacketBufferHandle BorrowTxPacket() { return mTxBuf.Retain(); }
+    void ClearTxPacket() { (void) TakeTxPacket(); }
 
     void LogState() const;
     void LogStateDebug() const;

src/inet/IPEndPointBasis.cpp

@@ -806,7 +806,7 @@ INET_ERROR IPEndPointBasis::SendMsg(const IPPacketInfo * aPktInfo, chip::System:
     VerifyOrExit(mAddrType == aPktInfo->DestAddress.Type(), res = INET_ERROR_BAD_ARGS);
 
     // For now the entire message must fit within a single buffer.
-    VerifyOrExit(aBuffer->Next() == nullptr, res = INET_ERROR_MESSAGE_TOO_LONG);
+    VerifyOrExit(!aBuffer->HasChainedBuffer(), res = INET_ERROR_MESSAGE_TOO_LONG);
 
     memset(&msgHeader, 0, sizeof(msgHeader));