From e0a6ca96cc071c7b02fb024d34a8902e636d0653 Mon Sep 17 00:00:00 2001
From: Markus Heiser <markus.heiser@darmarit.de>
Date: Thu, 27 Oct 2022 19:21:17 +0200
Subject: [PATCH] [doc] add a description of bing engines (web, news, video,
 images)

Signed-off-by: Markus Heiser <markus.heiser@darmarit.de>
---
 docs/src/searx.engines.bing.rst | 43 +++++++++++++++++++++++++++++++++
 searx/engines/bing.py           | 27 ++++++++++++++++++---
 2 files changed, 67 insertions(+), 3 deletions(-)
 create mode 100644 docs/src/searx.engines.bing.rst

diff --git a/docs/src/searx.engines.bing.rst b/docs/src/searx.engines.bing.rst
new file mode 100644
index 000000000..6b7bba8f2
--- /dev/null
+++ b/docs/src/searx.engines.bing.rst
@@ -0,0 +1,43 @@
+.. _bing engines:
+
+============
+Bing Engines
+============
+
+.. contents:: Contents
+   :depth: 2
+   :local:
+   :backlinks: entry
+
+
+.. _bing web engine:
+
+Bing WEB
+========
+
+.. automodule:: searx.engines.bing
+  :members:
+
+.. _bing images engine:
+
+Bing Images
+===========
+
+.. automodule:: searx.engines.bing_images
+  :members:
+
+.. _bing videos engine:
+
+Bing Videos
+===========
+
+.. automodule:: searx.engines.bing_videos
+  :members:
+
+.. _bing news engine:
+
+Bing News
+=========
+
+.. automodule:: searx.engines.bing_news
+  :members:
diff --git a/searx/engines/bing.py b/searx/engines/bing.py
index 385c973cb..0f85c7036 100644
--- a/searx/engines/bing.py
+++ b/searx/engines/bing.py
@@ -1,10 +1,31 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # lint: pylint
-"""Bing (Web)
+"""This is the implementation of the Bing-WEB engine. Some of this
+implementations are shared by other engines:
+
+- :ref:`bing images engine`
+- :ref:`bing news engine`
+- :ref:`bing videos engine`
+
+On the `preference page`_ Bing offers a lot of languages an regions (see section
+'Search results languages' and 'Country/region').  However, the abundant choice
+does not correspond to reality, where Bing has a full-text indexer only for a
+limited number of languages.  By example: you can select a language like Māori
+but you never get a result in this language.
+
+What comes a bit closer to the truth are the `search-APIs`_ but they don`t seem
+to be completely correct either (if you take a closer look you will find some
+inaccuracies there too):
+
+- :py:obj:`searx.engines.bing.bing_traits_url`
+- :py:obj:`searx.engines.bing_videos.bing_traits_url`
+- :py:obj:`searx.engines.bing_images.bing_traits_url`
+- :py:obj:`searx.engines.bing_news.bing_traits_url`
+
+.. _preference page: https://www.bing.com/account/general
+.. _search-APIs: https://learn.microsoft.com/en-us/bing/search-apis/
 
-- https://github.com/searx/searx/issues/2019#issuecomment-648227442
 """
-
 # pylint: disable=too-many-branches, invalid-name
 
 from typing import TYPE_CHECKING