Apply suggestions from code review

Co-authored-by: Ken Jin <[email protected]>
Co-authored-by: Peter Bierma <[email protected]>
Co-authored-by: Brandt Bucher <[email protected]>

Author: 4 people

InternalDocs/interpreter.md

@@ -506,16 +506,15 @@ After the last `DEOPT_IF` has passed, a hit should be recorded with
 After an optimization has been deferred in the adaptive instruction,
 that should be recorded with `STAT_INC(BASE_INSTRUCTION, deferred)`.
 
+
 ## How to add a new bytecode specialization
 
-Assuming you found an instruction that serves as a good specialization candidate. 
-Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
+Let's say you found an instruction that serves as a good specialization candidate, such as [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
 
-1. Update below in [Python/bytecodes.c](../Python/bytecodes.c)
+1. Make necessary changes to the instruction in [Python/bytecodes.c](../Python/bytecodes.c)
 
-- Convert `CONTAINS_OP` to a micro-operation (uop) by renaming
-     it to `_CONTAINS_OP` and changing the instruction definition
-     from `inst` to `op`.
+- Convert the instruction (`CONTAINS_OP`, in our example) to a micro-operation (uop, formally μop) by renaming it to `_INSTRUCTION_NAME` (e.g., `_CONTAINS_OP`) and changing the instruction definition
+from `inst` to `op`.
 
   ```c
         // Before
@@ -532,7 +531,7 @@ Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
             #if ENABLE_SPECIALIZATION
             if (ADAPTIVE_COUNTER_IS_ZERO(counter)) {
                 next_instr = this_instr;
-                _Py_Specialize_ContainsOp(right, next_instr);
+                _Py_Specialize_ContainsOp(left, right, next_instr);
                 DISPATCH_SAME_OPARG();
             }
             STAT_INC(CONTAINS_OP, deferred);
@@ -541,30 +540,29 @@ Let's use the example of [`CONTAINS_OP`](../Doc/library/dis.rst#contains_op):
         }
   ```
 
-- Create a macro for the original bytecode name:
+- Create a macro for the original instruction name:
 
   ```c 
   macro(CONTAINS_OP) = _SPECIALIZE_CONTAINS_OP + _CONTAINS_OP; 
   ``` 
 
-2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h),
-at the very least, a 16-bit counter is needed.
+2. Define the cache structure in [Include/internal/pycore_code.h](../Include/internal/pycore_code.h). It needs to have at least a 16-bit counter field.
 
     ```c
         typedef struct {
             uint16_t counter;
         } _PyContainsOpCache;
     ```      
 
-3. Write the specializing function itself (`_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c). 
+3. Write the specializing function itself (e.g., `_Py_Specialize_ContainsOp`) in [Python/specialize.c ](../Python/specialize.c). 
 Refer to other functions in that file for the pattern.
 
-4. Add a call to `add_stat_dict` in  `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).
+4. Add a call to `add_stat_dict` in `_Py_GetSpecializationStats` which is in [Python/specialize.c ](../Python/specialize.c).
 
-5. Add the cache layout in [Lib/opcode.py](../Lib/opcode.py) so that Python's 
-   `dis` module will know how to represent it properly.
+5. Add the cache layout to [Lib/opcode.py](../Lib/opcode.py) so that the 
+`dis` module will know how to represent it properly.
 
-6. Bump magic number in  [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
+6. Bump magic number in [Include/core/pycore_magic_number.h](../Include/internal/pycore_magic_number.h).
 
 7. Run ``make regen-all`` on `*nix` or `build.bat --regen` on Windows.