gh-156725: document O(N) behavior of PyCode_Addr2Line and the private line-table API

Doc/c-api/code.rst

@@ -94,11 +94,27 @@ bound into a function.
 
 .. c:function:: int PyCode_Addr2Line(PyCodeObject *co, int byte_offset)
 
-    Return the line number of the instruction that occurs on or before ``byte_offset`` and ends after it.
+    Return the line number of the instruction that occurs on or before
+    ``byte_offset`` and ends after it.  This is ``O(N)`` in the number of
+    instructions in the code object, so it is not suitable for iterating over
+    all the line numbers in a code object.
+
     If you just need the line number of a frame, use :c:func:`PyFrame_GetLineNumber` instead.
 
-    For efficiently iterating over the line numbers in a code object, use :pep:`the API described in PEP 626
-    <0626#out-of-process-debuggers-and-profilers>`.
+    To iterate efficiently over the line numbers in a code object, use the
+    private, unstable line-table iteration APIs declared in the private header
+    ``Include/internal/pycore_code.h``:
+
+    * ``_PyCode_InitAddressRange`` initializes a ``PyCodeAddressRange`` for a code object.
+    * ``_PyLineTable_NextAddressRange`` advances the range to the next
+      line-number entry.
+    * ``_PyLineTable_PreviousAddressRange`` retreats the range to the
+      previous entry.
+
+    .. warning::
+       These functions are **internal and not a public C-API**.  They are
+       declared in a private header, may change or be removed without notice,
+       and are not exported as stable symbols.
 
 .. c:function:: int PyCode_Addr2Location(PyObject *co, int byte_offset, int *start_line, int *start_column, int *end_line, int *end_column)