cleanup doc

Author: facontidavide

docs/PORT_CONNECTION_RULES.md

@@ -21,26 +21,21 @@ InputPort<Position2D>("goal")
 ### 2. Generic/Weakly Typed Ports (AnyTypeAllowed)
 
 A port is **generic** (not strongly typed) when:
-- Declared without a type parameter: `InputPort<>("my_port")`
-- Declared with `AnyTypeAllowed`: `InputPort<AnyTypeAllowed>("my_port")`
-- Declared with `BT::Any`: `InputPort<BT::Any>("my_port")`
+- Declared without a type parameter
+- Declared with `AnyTypeAllowed`
+- Declared with `BT::Any`
+- Declared with `std::string` (**OoutputPort** only)
 
 ```cpp
 // All of these create generic ports:
 InputPort<>("value")                    // defaults to AnyTypeAllowed
 InputPort<AnyTypeAllowed>("value")      // explicit AnyTypeAllowed
 InputPort<BT::Any>("value")             // BT::Any type
+OoutputPort<std::string>("value")       // Can be connected to strong typed input
 ```
 
 The `isStronglyTyped()` method returns `false` for these ports:
 
-```cpp
-// From basic_types.h
-bool isStronglyTyped() const
-{
-  return type_info_ != typeid(AnyTypeAllowed) && type_info_ != typeid(BT::Any);
-}
-```
 
 ## Port Connection Rules
 
@@ -49,13 +44,9 @@ bool isStronglyTyped() const
 Ports of the **exact same type** can always be connected:
 
 ```cpp
-// Node A
+// Connection allowed
 OutputPort<int>("value")    // writes int
-
-// Node B
 InputPort<int>("value")     // reads int
-
-// Connection: OK
 ```
 
 **Test reference:** `gtest_port_type_rules.cpp` - `SameType_IntToInt`, `SameType_StringToString`, `SameType_CustomTypeToCustomType` tests
@@ -65,13 +56,9 @@ InputPort<int>("value")     // reads int
 A **generic port** (`AnyTypeAllowed` or `BT::Any`) can connect to any other port:
 
 ```cpp
-// Node A with generic output
+// Connection: OK - generic port accepts any type
 OutputPort<>("output")           // generic, can write anything
-
-// Node B with typed input
 InputPort<int>("input_int")      // expects int
-
-// Connection: OK - generic port accepts any type
 ```
 
 **Test reference:** `gtest_port_type_rules.cpp` - `GenericPort_AcceptsInt`, `GenericPort_AcceptsString`, `GenericOutput_ToTypedInput` tests
@@ -80,24 +67,13 @@ InputPort<int>("input_int")      // expects int
 
 When a blackboard entry is created as `std::string`, it can be connected to ports of **any type** that has a `convertFromString<T>()` specialization. This is the "string as generic port" rule.
 
-**Source:** `xml_parsing.cpp`
-```cpp
-// special case related to convertFromString
-bool const string_input = (prev_info->type() == typeid(std::string));
-
-if(port_type_mismatch && !string_input)
-{
-  // Error thrown only if NOT a string input
-  throw RuntimeError("The creation of the tree failed...");
-}
-```
+Note that this may cause a run-time error if the string is not convertible.
 
 **Example:**
 ```xml
 <Sequence>
     <!-- Creates blackboard entry "value" as string with value "42" -->
     <SetBlackboard value="42" output_key="value" />
-
     <!-- Reads "value" as int - OK because string can convert to int -->
     <NodeExpectingInt input="{value}" />
 </Sequence>
@@ -113,15 +89,6 @@ if(port_type_mismatch && !string_input)
 
 When using `Blackboard::set<std::string>()`, the entry is created with `AnyTypeAllowed` type, not `std::string`:
 
-**Source:** `blackboard.h`
-```cpp
-// if a new generic port is created with a string, it's type should be AnyTypeAllowed
-if constexpr(std::is_same_v<std::string, T>)
-{
-  entry = createEntryImpl(key, PortInfo(PortDirection::INOUT));  // AnyTypeAllowed
-}
-```
-
 This allows subsequent writes of different types to the same entry.
 
 **Test reference:** `gtest_port_type_rules.cpp` - `BlackboardSetString_CreatesGenericEntry`, `StringEntry_CanBecomeTyped` tests
@@ -130,37 +97,15 @@ This allows subsequent writes of different types to the same entry.
 
 Once a blackboard entry receives a **strongly typed** value, its type is locked:
 
-**Source:** `blackboard.h`
-```cpp
-// special case: entry exists but it is not strongly typed... yet
-if(!entry.info.isStronglyTyped())
-{
-  // Use the new type to create a strongly typed entry
-  entry.info = TypeInfo::Create<T>();
-  // ...
-  return;
-}
-```
-
-After this, writing a different type will fail (with exceptions noted below).
+After this, writing a different type will fail (with exception).
 
 **Test reference:** `gtest_port_type_rules.cpp` - `TypeLock_CannotChangeAfterTypedWrite`, `TypeLock_XMLTreeCreation_TypeMismatch`, `TypeLock_RuntimeTypeChange_Fails` tests
 
 ### Rule 6: BT::Any Bypasses Type Checking
 
-When a blackboard entry is **created with type `BT::Any`**, it can store different types over time. This requires the entry to be explicitly created as `BT::Any` type.
+When a blackboard entry is **created with type `BT::Any`**, it can store different types over time.
 
-**Important:** Wrapping a value with `BT::Any()` does **not** bypass type checking - the wrapper is unwrapped and the inner type is used:
-
-```cpp
-// This creates an entry of type int, NOT BT::Any
-bb->set("key", BT::Any(42));
-
-// This will FAIL - entry is int, not BT::Any
-bb->set("key", BT::Any("hello"));  // throws LogicError
-```
-
-To actually allow different types, create the entry as `BT::Any`:
+This requires the entry to be explicitly created as `BT::Any` type.
 
 ```cpp
 // Create entry explicitly as BT::Any type
@@ -282,56 +227,3 @@ The following names **cannot** be used for ports:
 - Names starting with `_` - Reserved for internal use
 
 **Test reference:** `gtest_port_type_rules.cpp` - `ReservedPortName_ThrowsOnRegistration` test
-
-## Common Patterns
-
-### Pattern 1: Type-Safe Port Chain
-```xml
-<Sequence>
-    <CalculateGoal goal="{GoalPosition}" />      <!-- Output: Position2D -->
-    <PrintTarget target="{GoalPosition}" />      <!-- Input: Position2D -->
-</Sequence>
-```
-
-### Pattern 2: String Literal to Typed Port
-```xml
-<Sequence>
-    <SetBlackboard value="1.5;2.5" output_key="pos" />
-    <MoveToPosition target="{pos}" />  <!-- Converts string to Position2D -->
-</Sequence>
-```
-
-### Pattern 3: Generic Intermediate Storage
-```xml
-<Sequence>
-    <TypedNode output_int="{value}" />     <!-- Writes int to generic entry -->
-    <GenericNode input="{value}" />        <!-- Generic port reads it -->
-    <AnotherTypedNode input_int="{value}"/> <!-- Int port reads it -->
-</Sequence>
-```
-
-## Error Messages
-
-Common type-related errors:
-
-1. **"The creation of the tree failed because the port [X] was initially created with type [A] and, later type [B] was used somewhere else."**
-   - Cause: Two nodes use same blackboard key with incompatible types
-   - Solution: Ensure consistent types or use string/generic ports
-
-2. **"Blackboard::set(X): once declared, the type of a port shall not change."**
-   - Cause: Runtime attempt to change entry type
-   - Solution: Use consistent types or BT::Any
-
-3. **"The port with name X and value Y can not be converted to Z"**
-   - Cause: Literal value cannot be parsed to port type
-   - Solution: Fix value format or add `convertFromString` specialization
-
-## References
-
-- Source: `include/behaviortree_cpp/basic_types.h` - Type system definitions
-- Source: `include/behaviortree_cpp/blackboard.h` - Blackboard type checking
-- Source: `src/xml_parsing.cpp` - Tree creation validation
-- Tests: `tests/gtest_port_type_rules.cpp` - Comprehensive port type rule tests
-- Tests: `tests/gtest_ports.cpp` - Port connection tests
-- Tests: `tests/gtest_blackboard.cpp` - Blackboard tests
-- Tutorial: `examples/t03_generic_ports.cpp` - Custom type example