Move comments into Doc/c-api, fix documented string length

Comment says 100, but it appears to have been 500 since 2012,
alexmalyshev@54f939b.

Author: alexmalyshev

Doc/c-api/exceptions.rst

@@ -1349,17 +1349,55 @@ Tracebacks
 
 .. c:function:: void PyUnstable_DumpTraceback(int fd, PyThreadState *tstate)
 
-   Write a trace of the Python stack in *tstate* into the file *fd*.
+   Write a trace of the Python stack in *tstate* into the file *fd*.  The format
+   looks like::
+
+      Traceback (most recent call first):
+            File "xxx", line xxx in <xxx>
+            File "xxx", line xxx in <xxx>
+            ...
+            File "xxx", line xxx in <xxx>
+
+   This function is meant to debug situations such as segfaults, fatal errors,
+   .etc. The file and function names it outputs are encoded to ASCII with
+   backslashreplace and truncated to 500 characters. It writes only the first
+   100 frames, further frames are truncated with the line " ...".
 
    This function is safe to use from signal handlers.
 
+   The caller does not need to hold an :term:`attached thread state`, nor does
+   *tstate* need to be attached.
+
+   .. versionadded:: next
+
 .. c:function:: const char* PyUnstable_DumpTracebackThreads(int fd, PyInterpreterState *interp, PyThreadState *current_tstate)
 
-   Write the traces of all Python threads in *interp* into the file *fd*.  If
-   *current_state* is not NULL then it will be used to identify what the current
-   thread is in the written output. If it is NULL then this function will
-   identify the current thread using thread-specific storage.
+   Write the traces of all Python threads in *interp* into the file *fd*.
+
+   If *interp* is ``NULL`` then this function will try to identify the current
+   interpreter using thread-specific storage. If it cannot, it will return an
+   error.
+
+   If *current_tstate* is not ``NULL`` then it will be used to identify what the
+   current thread is in the written output. If it is ``NULL`` then this function
+   will identify the current thread using thread-specific storage. It is not an
+   error if the function is unable to get the current Python thread state.
 
-   This function will return NULL on success, or an error message on error.
+   This function will return ``NULL`` on success, or an error message on error.
+
+   This function is meant to debug debug situations such as segfaults, fatal
+   errors, .etc. It calls :c:func:`PyUnsafe_DumpTraceback` for each thread. It
+   only writes the tracebacks of the first 100 threads, further output is
+   truncated with the line " ...".
 
    This function is safe to use from signal handlers.
+
+   The caller does not need to hold an :term:`attached thread state`, nor does
+   *current_tstate* need to be attached.
+
+   .. warning::
+      On the :term:`free-threaded build`, this function is not thread-safe. If
+      another thread deletes its :term:`thread state` while this function is being
+      called, the process will likely crash.
+
+   .. versionadded:: next

Include/cpython/traceback.h

@@ -12,46 +12,8 @@ struct _traceback {
     int tb_lineno;
 };
 
-/* Write the Python traceback into the file 'fd'. For example:
-
-       Traceback (most recent call first):
-         File "xxx", line xxx in <xxx>
-         File "xxx", line xxx in <xxx>
-         ...
-         File "xxx", line xxx in <xxx>
-
-   This function is written for debug purpose only, to dump the traceback in
-   the worst case: after a segmentation fault, at fatal error, etc. That's why,
-   it is very limited. Strings are truncated to 100 characters and encoded to
-   ASCII with backslashreplace. It doesn't write the source code, only the
-   function name, filename and line number of each frame. Write only the first
-   100 frames: if the traceback is truncated, write the line " ...".
-
-   This function is signal safe. */
 PyAPI_FUNC(void) PyUnstable_DumpTraceback(int fd, PyThreadState *tstate);
 
-/* Write the traceback of all threads into the file 'fd'. current_thread can be
-   NULL.
-
-   Return NULL on success, or an error message on error.
-
-   This function is written for debug purpose only. It calls
-   PyUnstable_DumpTraceback() for each thread, and so has the same limitations. It
-   only writes the traceback of the first 100 threads: write "..." if there are
-   more threads.
-
-   If current_tstate is NULL, the function tries to get the Python thread state
-   of the current thread. It is not an error if the function is unable to get
-   the current Python thread state.
-
-   If interp is NULL, the function tries to get the interpreter state from
-   the current Python thread state, or from
-   _PyGILState_GetInterpreterStateUnsafe() in last resort.
-
-   It is better to pass NULL to interp and current_tstate, the function tries
-   different options to retrieve this information.
-
-   This function is signal safe. */
 PyAPI_FUNC(const char*) PyUnstable_DumpTracebackThreads(
     int fd,
     PyInterpreterState *interp,