Skip to content

JuliaSyntax: Add a brief docstring for JuliaSyntax.build_tree - #63206

Merged
DilumAluthge merged 1 commit into
masterfrom
dpa/juliasyntax-public-api-fixes
Sep 17, 2026
Merged

DilumAluthge merged 1 commit into
masterfrom
dpa/juliasyntax-public-api-fixes

Conversation

@DilumAluthge

@DilumAluthge DilumAluthge commented Sep 16, 2026

Copy link
Copy Markdown
Member

JuliaSyntax/docs/src/api.md currently has the following:

```@docs
JuliaSyntax.parse!
JuliaSyntax.ParseStream
JuliaSyntax.build_tree
```

But JuliaSyntax.build_tree doesn't currently have a docstring, so the docs build will fail. This PR adds a minimal docstring.

🤖 Assisted-by: Claude Code:Opus 5

@DilumAluthge
DilumAluthge added this pull request to stack #63209 September 16, 2026 04:51
@DilumAluthge DilumAluthge changed the title dpa/juliasyntax public api fixes JuliaSyntax: Fix gaps in the public API surface Sep 16, 2026
Comment thread JuliaSyntax/src/julia/parser_api.jl Outdated
Comment thread JuliaSyntax/docs/src/api.md Outdated
Comment thread JuliaSyntax/src/core/parse_stream.jl Outdated
Comment thread JuliaSyntax/src/JuliaSyntax.jl Outdated
Comment thread JuliaSyntax/src/JuliaSyntax.jl Outdated
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch 2 times, most recently from 35086ae to debd2b5 Compare September 16, 2026 05:08
@DilumAluthge
DilumAluthge removed this pull request from stack #63209 September 16, 2026 05:09
@DilumAluthge
DilumAluthge added this pull request to stack #63211 September 16, 2026 05:09
@DilumAluthge DilumAluthge changed the title JuliaSyntax: Fix gaps in the public API surface JuliaSyntax: Add a docstring for build_tree Sep 16, 2026
@DilumAluthge
DilumAluthge removed this pull request from stack #63211 September 16, 2026 05:12
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from debd2b5 to 3eee1cd Compare September 16, 2026 05:12
@DilumAluthge
DilumAluthge changed the base branch from master to dpa/juliasyntax-drop-dangling-names September 16, 2026 05:13
@DilumAluthge
DilumAluthge added this pull request to stack #63213 September 16, 2026 05:13
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from 3eee1cd to 89efc4b Compare September 16, 2026 05:21
@DilumAluthge

Copy link
Copy Markdown
Member Author

@mlechu @topolarity What do you think of creating a docstring for build_tree, vs just removing build_tree from the @docs blocks. I think either would be sufficient for the purposes of fixing the docs build.

@DilumAluthge

DilumAluthge commented Sep 16, 2026

Copy link
Copy Markdown
Member Author

(IIUC, the JuliaSyntax repo set this kind of thing to be a warning when building the docs, but in the Julia repo, I think we make it a hard error that fails the docs build.)

@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from 89efc4b to 49304ef Compare September 16, 2026 05:28
@DilumAluthge DilumAluthge changed the title JuliaSyntax: Add a docstring for build_tree JuliaSyntax: Add sdocstring for the methods of build_tree Sep 16, 2026
@DilumAluthge DilumAluthge changed the title JuliaSyntax: Add sdocstring for the methods of build_tree JuliaSyntax: Add docstrings for the methods of build_tree Sep 16, 2026

@mlechu mlechu left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I'd prefer either removal of build_tree from the docs block, or a single docstring above function build_tree end (something like "Build a tree of type type from a raw parsed stream ps. This is the final step in parsing."

Base automatically changed from dpa/juliasyntax-drop-dangling-names to master September 16, 2026 17:58
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from 49304ef to d309b07 Compare September 16, 2026 17:58
@DilumAluthge

Copy link
Copy Markdown
Member Author

Sounds good. Do you have a preference between those two options?

@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from d309b07 to cc80f5f Compare September 16, 2026 18:15
@mlechu

mlechu commented Sep 16, 2026

Copy link
Copy Markdown
Member

No strong preference, just remove it if you're unsure. I think most consumers call some string->T driver function instead of doing the ParseStream -> parse! -> build_tree dance

@DilumAluthge DilumAluthge changed the title JuliaSyntax: Add docstrings for the methods of build_tree JuliaSyntax: Remove JuliaSyntax.build_tree from the @docs block Sep 16, 2026
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from cc80f5f to a2b4203 Compare September 16, 2026 22:22
@DilumAluthge DilumAluthge changed the title JuliaSyntax: Remove JuliaSyntax.build_tree from the @docs block JuliaSyntax: Remove JuliaSyntax.build_tree from the @docs block in api.md Sep 16, 2026
@DilumAluthge DilumAluthge changed the title JuliaSyntax: Remove JuliaSyntax.build_tree from the @docs block in api.md JuliaSyntax: Add a brief docstring for JuliaSyntax.build_tree Sep 16, 2026
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from a2b4203 to 7c99a5f Compare September 16, 2026 22:26
@DilumAluthge
DilumAluthge marked this pull request as ready for review September 16, 2026 22:26
`build_tree` is listed in the `@docs` block in `api.md` and is referenced with
`@ref` from the `parse!` docstring, but had no docstring, so neither could
resolve. Add a single docstring on a `function build_tree end` stub, as
suggested in review.

Assisted-by: Claude Code (Opus 5)

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
@DilumAluthge
DilumAluthge force-pushed the dpa/juliasyntax-public-api-fixes branch from 7c99a5f to de49dc9 Compare September 16, 2026 22:26
@DilumAluthge

Copy link
Copy Markdown
Member Author

It looks like some other docstrings have @refs to build_tree, so I ended up going with the "single docstring" approach.

@DilumAluthge
DilumAluthge requested a review from mlechu September 16, 2026 22:27
@DilumAluthge DilumAluthge added the merge me PR is reviewed. When all tests are passing merge, making sure commit message is good. label Sep 16, 2026
@DilumAluthge
DilumAluthge merged commit 272aa7e into master Sep 17, 2026
9 of 11 checks passed
@DilumAluthge
DilumAluthge deleted the dpa/juliasyntax-public-api-fixes branch September 17, 2026 15:27
@DilumAluthge DilumAluthge removed the merge me PR is reviewed. When all tests are passing merge, making sure commit message is good. label Sep 17, 2026
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