[website] Improve documentation of MIXED_SELF_WEAKSELF

Summary: Adding examples

Reviewed By: ezgicicek

Differential Revision: D32648754

fbshipit-source-id: c2af3f0d62

Author: dulmarod

infer/documentation/issues/MIXED_SELF_WEAKSELF.md

@@ -1,4 +1,22 @@
-This happens when an Objective-C block captures both `self` and `weakSelf`, a
-weak pointer to `self`. Possibly the developer meant to capture only `weakSelf`
-to avoid a retain cycle, but made a typo and used `self` as well in the block,
+This check reports an issue when an Objective-C block captures both `self` and `weakSelf`, a weak pointer to `self`.
+Possibly the developer meant to capture only `weakSelf` to avoid a retain cycle, but made a typo and used `self`
 instead of `strongSelf`. In this case, this could cause a retain cycle.
+
+Example:
+
+```objectivec
+  __weak __typeof(self) weakSelf = self;
+  int (^my_block)() = ^() {
+    __strong __typeof(weakSelf) strongSelf = weakSelf;
+    if (strongSelf) {
+      [strongSelf foo];
+      int x = self->x; // typo here
+    }
+    return 0;
+  };
+```
+
+**Action**: Fixing the typo is generally the right course of action.
+
+*Limitations:* To keep this check simple and intra-procedural, we rely on names to find `weakSelf`:
+we assume that any captured weak pointer whose name contains "self" is a weak reference to `self`.

website/docs/all-issue-types.md

@@ -1459,11 +1459,29 @@ As explained by the analysis.
 
 Reported as "Mixed Self WeakSelf" by [self-in-block](/docs/next/checker-self-in-block).
 
-This happens when an Objective-C block captures both `self` and `weakSelf`, a
-weak pointer to `self`. Possibly the developer meant to capture only `weakSelf`
-to avoid a retain cycle, but made a typo and used `self` as well in the block,
+This check reports an issue when an Objective-C block captures both `self` and `weakSelf`, a weak pointer to `self`.
+Possibly the developer meant to capture only `weakSelf` to avoid a retain cycle, but made a typo and used `self`
 instead of `strongSelf`. In this case, this could cause a retain cycle.
 
+Example:
+
+```objectivec
+  __weak __typeof(self) weakSelf = self;
+  int (^my_block)() = ^() {
+    __strong __typeof(weakSelf) strongSelf = weakSelf;
+    if (strongSelf) {
+      [strongSelf foo];
+      int x = self->x; // typo here
+    }
+    return 0;
+  };
+```
+
+**Action**: Fixing the typo is generally the right course of action.
+
+*Limitations:* To keep this check simple and intra-procedural, we rely on names to find `weakSelf`:
+we assume that any captured weak pointer whose name contains "self" is a weak reference to `self`.
+
 ## MODIFIES_IMMUTABLE
 
 Reported as "Modifies Immutable" by [impurity](/docs/next/checker-impurity).