Improve documentation of instrumentation's sqlcommenter feature

[tammy-baylis-swi]

What problem do you want to solve?

sqlcommenter / sqlcommenting is a feature that some of the Python database client instrumentors have supported for some years now, at different levels and through a variety of implementations:

1. psycopg2
2. psycopg
3. mysqlclient/MySQLdb
4. PyMySQL
5. SQLAlchemy
6. Django ORM
7. Flask

For 1-4, the implementation is inherited through the DB-API instrumentor.

From the above docs, it might not be immediately clear to users what this feature does and when to use it. It may also be difficult for contributing developers to onboard.

Describe the solution you'd like

Update the documentation of Python database client instrumentors that support sqlcommenter. Potentially update in-code comments to point developers at key parts of implementation e.g. the inherited DB-API functions.

Describe alternatives you've considered

sqlcomment is not currently in the Otel semconv (database spec). I suggest a separate issue for TC proposal using these Python instrumentors as prototype/proof-of-concept.

Additional Context

Google's doc on sqlcommenter is helpful: https://google.github.io/sqlcommenter/

Would you like to implement a fix?

N/A