Skip to content

docs(devdocs): Add generated dev documentation #3364

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: master
Choose a base branch
from

Conversation

ndyakov
Copy link
Member

@ndyakov ndyakov commented Apr 29, 2025

Add AI generated dev documentation in the docs folder.

Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR adds AI-generated developer documentation in the docs folder to provide detailed technical guidance on testing, connection pooling, and command processing in the Redis client.

  • Introduces a new Redis Testing Guide (docs/redis_testing.md) with setup instructions and test examples.
  • Adds a comprehensive documentation of the Redis connection pool (docs/redis_pool.md), including configuration and implementation details.
  • Provides an overview of Redis command processing (docs/redis_command_processing.md) and updates related README files for better navigation and context.

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
docs/redis_testing.md New guide with instructions for environment setup, testing, and examples.
docs/redis_pool.md Detailed documentation on connection pooling concepts and implementation.
docs/redis_command_processing.md Description of command processing flows and best practices.
docs/README.md Overview of the documentation structure highlighting key files.
README.md Updates to include a link to the AI-generated developer documentation.
Comments suppressed due to low confidence (1)

docs/redis_pool.md:92

  • [nitpick] The field name 'idleConnsLen' could be less clear than a name like 'idleConnCount' for representing the number of idle connections. Renaming it may improve code clarity and consistency with other naming conventions.
idleConnsLen int

Add AI generated dev documentation in the `docs` folder.
@ndyakov ndyakov force-pushed the ndyakov/ai-generated-docs branch from 9f258c1 to f316244 Compare April 29, 2025 20:37
@ndyakov ndyakov force-pushed the ndyakov/ai-generated-docs branch from 516d9b3 to c14645c Compare April 29, 2025 20:45
@andy-stark-redis
Copy link
Contributor

@ndyakov I've mentioned some specific points below, but TL;DR is that I'm not sure this really works as it stands.

It's a great idea to provide docs that will help people to contribute to the client library code. However, advice about good practice, performance, good error handling, etc, is information that would be worth having in the main redis.io docs where end users of the client can easily find it. Some of the client libraries had this kind of info in the Github repo before there was any documentation about it on redis.io, which is the main reason why they still have docs folders. However, for go-redis, we should aim to get this stuff directly onto redis.io and maybe just link to it from Github if necessary.

(BTW, I'm currently adding pages with production usage guidelines for all the clients, so some of the stuff in this PR would probably work well in the Go production usage page.)

Anyway, some thoughts are below. Some of these maybe could be fixed by refining the prompt or using a separate focused prompt for each page you want to produce:

  1. Most of the docs are in the form of bullet lists. They provide a very short summary of each point (a bit like a PowerPoint presentation) but they don't explain the subject in very much detail or link to another place where a longer explanation is provided.

  2. The pages clients-and-connections.md and general-architecture.md are very long. They seem to discuss all sorts of different subjects rather than focusing on a specific topic. Perhaps these topics should be broken down into smaller bits? (For example, transactions/pipelines probably deserves a separate page rather than a section in clients and connections).

  3. clients-and-connections.md has lots of diagrams. They seem to be of good quality (although some are very big onscreen) and I definitely think that diagrams can often help with an explanation. However, there are several quite complicated diagrams in this page, one after another, with little or no explanatory text in between. It's much better to have one diagram, then the explanation, then the next diagram, then next explanation, etc.

  4. Parts like this contain descriptions of code properties, functions, etc. It seems like it might be better to use AI to add doc comments for this kind of information. It would appear in the text editor as tooltips and if you need to link to it, it would be available in the API docs anyway.

  5. Some subjects (best practices, connection management, hooks) seem to be discussed in several places. Users don't really want to keep reading the same info repeatedly and don't want to have to look in several different files to find all the info about a particular topic. It's best if the docs stick to one main subject per page and gather all the info about it together in one place.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants