docs: fix stale #543 iterator-API residue in doc sources - #1051
Merged
Conversation
The alibaba#543 refactor replaced QueryResult's iterator API (begin/end over RecordLine) with a cursor API (hasNext/next/GetXxx/GetCurrentRowAsString), but several documentation *sources* still carried the old iterator form. The published reference docs were already hand-corrected, so this commit only fixes the upstream sources -- headers, the generator and its config, and one Python docstring -- keeping them consistent with the shipped docs and preventing a future regeneration from reintroducing the residue. No generated reference docs are changed. - include/neug/main/connection.h: both usage examples now use the cursor API - include/neug/main/neug_db.h: usage example uses the cursor API; clarify file-locking semantics (read-write is exclusive, read-only can share the same directory across processes/instances) - doc/source/_scripts/generate_cpp_docs.py: cursor API in the index usage templates; emit the _meta.ts default export with a trailing semicolon - doc/source/_scripts/cpp_key_classes.json: drop the non-existent neug::RecordLine; describe QueryResult as cursor-based - tools/python_bind/neug/session.py: access_mode "" means "infer from the query text", not "update (default)"; move the transaction note into the description body
zhanglei1949
requested review from
liulx20 and
longbinlai
and
a lite review from Copilot
and removed request for
longbinlai
September 10, 2026 07:47
liulx20
approved these changes
Sep 10, 2026
Contributor
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Pull request overview
Updates stale documentation sources to reflect the post-#543 cursor-based QueryResult API and fixes generator/config remnants from the iterator-era docs.
Changes:
- Refresh C++ header examples and generator templates to use the cursor API (
hasNext()/next()/ typed getters / row string helpers). - Fix doc-generator output for
_meta.tsby emitting a valid C++/TS struct/object terminator (};). - Clean up C++ doc generator config by removing retired
neug::RecordLinereferences and updatingQueryResultdescriptions.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/python_bind/neug/session.py | Adjusts Session.execute() docstring to explain access-mode inference and improves rendering of transaction behavior notes. |
| include/neug/main/neug_db.h | Updates quick-start example to cursor API and clarifies file-locking semantics for read-write vs read-only opens. |
| include/neug/main/connection.h | Replaces iterator-based examples with cursor-based walkthroughs and shows typed access. |
| doc/source/_scripts/generate_cpp_docs.py | Updates embedded templates to cursor API, corrects _meta.ts emission, and updates QueryResult wording. |
| doc/source/_scripts/cpp_key_classes.json | Removes retired key class (RecordLine) and aligns QueryResult description with cursor API. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+1307
to
+1308
| std::cout << qr.GetCurrentRowAsString() << std::endl; | ||
| qr.next(); |
Comment on lines
+1515
to
+1516
| std::cout << qr.GetCurrentRowAsString() << std::endl; | ||
| qr.next(); |
Comment on lines
+50
to
+53
| * auto& qr = result.value(); | ||
| * while (qr.hasNext()) { | ||
| * std::cout << qr.GetCurrentRowAsString() << std::endl; | ||
| * qr.next(); |
Comment on lines
+117
to
+118
| * std::string name = qr.GetString("n.name"); | ||
| * qr.next(); |
Comment on lines
+81
to
+82
| * std::cout << qr.GetCurrentRowAsString() << std::endl; | ||
| * qr.next(); |
Comment on lines
+327
to
+328
| :param access_mode: The access mode for the query. When omitted, NeuG infers it | ||
| from the query text. Supported modes are: |
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
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.
What do these changes do?
Fix stale documentation sources left behind by the #543 iterator→cursor
QueryResultrefactor. These are doc sources only (header comments, the doc generator, its config, and a Python docstring) — no functional code changes, and no generated docs are committed (rationale below).include/neug/main/connection.h,include/neug/main/neug_db.h: replace the pre-refactor: replace iterator with cursor-based HasNext/Next/Get API #543for (auto& record : result.value())examples with the current cursor API (hasNext()/next()/GetString(...)/GetCurrentRowAsString()). Also expand theneug_db.hfile-locking note to match the already-published wording: a read-write open is exclusive, while multiple read-only processes/instances can share the directory.doc/source/_scripts/generate_cpp_docs.py: update the Quick Start example templates to the cursor API and fix a struct emission bug (content += "}"→"};", which previously produced invalid C++ in_meta.ts).doc/source/_scripts/cpp_key_classes.json: drop the retiredneug::RecordLinekey class and its danglinginclude_classesreference; align theQueryResultdescription to "cursor-based access".tools/python_bind/neug/session.py: correct theSession.execute()docstring — the defaultaccess_mode=""infers the mode from the query text, so remove the inaccurate "(default)" on update mode and document the inference; move the transaction-behavior note out of the:return:block so it renders.Why no generated docs are included
The published docs under
doc/source/reference/are hand-curated and already correct — several were fixed directly in #573/#892/#1003/#1025 without updating the sources. Re-running the generator (make html/make api-docs) produces a mix of catch-up and regressions, and the regressions would ship broken docs:cpp_api/query_result.md— docs: improve C++ API reference #1025's five sections (Cursor Traversal/Typed Value Accessors/Metadata/Other Methods/Example) collapse into a singlePublic Methodslist;cpp_api/service.md's hand-writtenExecutionSlotdescription ("runtime-neutral execution context…"), which lives in no header and therefore cannot be reproduced by generation;Person→person), breaks examples into invalid Cypher (-[:KNOWS]->→-[knows]->), and injects raw Sphinx:meth:roles that don't render on the docs site.So this PR deliberately fixes the sources only (a strict improvement, zero published-doc regression). Bringing the generated docs back in sync — correcting the stale Python docstrings and reconciling the hand-curated C++ pages so the generator reproduces the good output — is left as a separate follow-up.
Related issue number
N/A — follow-up cleanup to #543.