Clarification needed in ResGatedGraphConv documentation about edge feature usage

[aditya0by0]

Hi PyG team 👋,

I’ve been digging into the ResGatedGraphConv implementation and noticed a potential documentation gap.

Currently, the documentation presents the following equations:

$$x'_i = W_1 x_i + \sum_{j \in \mathcal{N}(i)} \eta_{ij} \odot W_2 x_j$$

with

$$ \eta_{ij} = \sigma(W_3 x_i + W_4 x_j). $$

This looks correct when no edge features are provided.
However, in the actual implementation (source), when edge_attr is passed, it is concatenated to the node features before computing key, query, and value projections:

if edge_attr is not None:
    k_i = self.lin_key(torch.cat([k_i, edge_attr], dim=-1))
    q_j = self.lin_query(torch.cat([q_j, edge_attr], dim=-1))
    v_j = self.lin_value(torch.cat([v_j, edge_attr], dim=-1))

This means the true behavior is closer to:

$$x'_i = W_1 x_i + \sum_{j \in \mathcal{N}(i)} \eta_{ij} \odot W_2(x_j \Vert e_{ij})$$

$$ \eta_{ij} = \sigma\bigl(W_3 (x_i \Vert e_{ij}) + W_4 (x_j \Vert e_{ij})\bigr), $$

where $e_{ij}$ are edge features.

---

Suggestion

It would be very helpful if the documentation could:

1. Explicitly mention how edge features are integrated (via concatenation).
2. Clarify that edge features are used as context in message passing but are not updated within this layer (unless combined with a separate edge_update step).

Edge feature is not updated directly, but used to transform node features differently depending on the edge. They’re not learned/updated over time (unless you explicitly add an edge_update() method).

I would be happy to create a PR to update the documentation if you think this needs to be clarified.