API section docs suggestions#15
Merged
krylosov-aa merged 6 commits intokrylosov-aa:mainfrom Jan 9, 2026
Merged
Conversation
index getting started problem it solves Base docs suggestions as per the commit message. Will open a separate PR for the other stuff I'd suggest in general.
…eferences sections, including the text represnted in code which has been COMMENTED OUT, NOT THE CODE ITSELF
I changed tenses to maintain present tense. The second POV is standard for docs, and it maintains consistency with the rest of your wording. Like "login" (noun) and "log in" (verb) , "rollback" and "rollsback" function as two different kinds of word. "rollback", the function and API call, is a noun. "Rolls back" is the verb, the act of calling a rollback. This is another docs standard thing so the user can tell whether you're describing a thing or telling them that thing is happening. Some of the API calls you named are clear enough not to need to redescribe them as a separate line. (gg!) Under run_in_new_ctx, used the code tag for "callable_func" even if it's an example, so it sticks out and is clear it needs to be an API call. If I made changes to the text about the code but that text was replicated inside code examples, I made those changes there, too. I did NOT touch anything else about your examples and the actual code therein. I tested all my work to make sure that didn't happen, but please feel free to call me on it if I messed that up. "An example of a handle that uses a session in context, but commits manually and even closes the session to release the connection" -> "An example of a handle that uses a session in context, but commits manually and closes the session to release the connection." "And here we closed the session = returned the connection to the pool. This is useful if, for example, at the beginning of the handle a database query is needed, and then there is some other long-term work and you don't want to keep the connection opened" -> "We closed the session and returned the connection to the pool" and "Use if you have more work you need to complete without keeping the connection open." "You don't have to use the context to work with sessions at all" -> "Using the context is option while working with sessions" "In some situations, you need to have multiple sessions running simultaneously" -> "You may need to run multiple sessions simultaneously" "transaction will be automatically rolled back" -> "transactions roll back automatically" "You can manually commit the transaction if you want, but it is not necessary" -> "manually commits the transaction (optional)" "You can close the session if you want, but it is not necessary" -> "manually closes the session (optional)"
Docs Changes to API Reference Section - index.html (API) - api.md Changes made - Tightening sentences - Small formatting changes (made a list toward the top of the section for readability - Small wording changes for the same reason - "rollback" as an API call and "rolling back" or "roll back" as a verb are unfortunately different and while the difference looks petty, it's a standard docs practice (e.g., "login" vs. "log in"). Really think you made a cool thing.
krylosov-aa
reviewed
Jan 9, 2026
| You can also use these same techniques to create new sessions whenever you | ||
| need them. Not necessarily just because of the concurrent processing. | ||
| You can also use the same techniques to create new sessions whenever you | ||
| need them, ot necessarily because of the concurrent processing. |
Owner
There was a problem hiding this comment.
A small typo, missing the n in the word not
krylosov-aa
reviewed
Jan 9, 2026
|
|
||
| You can also use these same techniques to create new sessions whenever you | ||
| need them. Not necessarily just because of the concurrent processing. | ||
| need themm, not necessarily because of the concurrent processing. |
Owner
|
Thank you so much for the work you have done. I really like the changes you've made. |
krylosov-aa
approved these changes
Jan 9, 2026
Owner
|
Don't worry about typos. I'll fix it myself when I sync the changes to other places. I actually wrote the documentation in .md, and then I use MkDocs to convert it to html. I can't say that it's very convenient, but so far it's the easiest way that I've found. |
Owner
|
I have synchronized the changes between If something is wrong, then edit in Thanks again for participating! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs Changes to API Reference Section
Changes made
Really think you made a cool thing.