[DONT MERGE] emit docs #2407
Open
[DONT MERGE] emit docs #2407
Conversation
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
imalsogreg
had a problem deploying
to
boundary-tools-dev
GitHub Actions
Failure
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
🔒 Entelligence AI Vulnerability Scanner ✅ No security vulnerabilities found! Your code passed our comprehensive security analysis. |
|
LGTM 👍 |
imalsogreg
force-pushed
the
greg/emit-docs
branch
from
9ef71f7 to
cbd8826
Compare
imalsogreg
had a problem deploying
to
boundary-tools-dev
GitHub Actions
Failure
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
![ellipsis-dev[bot]](https://avatars.githubusercontent.com/in/64358?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Changes requested ❌
Reviewed cbd8826 in 2 minutes and 44 seconds. Click for details.
- Reviewed
777lines of code in3files - Skipped
0files when reviewing. - Skipped posting
5draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. fern/01-guide/05-baml-advanced/runtime-events.mdx:6
- Draft comment:
Replace the placeholder 'TODO' in the Info block with the actual feature version when available. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 30% vs. threshold = 50% This is a documentation file and the TODO is clearly meant to be replaced with real information. However, the comment suggests a specific version (v1.2.3) without any evidence that this is the correct version. The comment is about something that changed (new file) but the suggestion seems speculative. The TODO needs to be replaced, so the comment identifies a real issue. But suggesting a specific version without evidence could be misleading. While the TODO needs to be fixed, making up a version number could cause more problems than it solves. The comment should be more general. The comment identifies a real issue but makes a speculative suggestion about the version number. A more general comment would be better.
2. fern/01-guide/05-baml-advanced/runtime-events.mdx:14
- Draft comment:
Typo: Change 'though' to 'through' in the sentence describing the event system. - Reason this comment was not posted:
Marked as duplicate.
3. fern/01-guide/05-baml-advanced/runtime-events.mdx:185
- Draft comment:
Consider updating the progress calculation to use (i + 1) instead of i if you intend the final update to reflect 100% completion. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% This is a legitimate issue - using i instead of (i+1) means the progress will never reach 100% since i is 0-based. However, this is a documentation example showing how to use events, not production code. The exact progress calculation isn't critical to demonstrating the events feature. The comment is technically correct but not important enough for the context. The progress calculation bug could confuse readers trying to learn from this example. Bad examples in documentation can propagate mistakes. While true, this is a minor implementation detail that doesn't affect understanding the core events concept being taught. The focus should be on how to use events, not progress calculation math. Delete the comment. While technically correct, it's a minor implementation detail in documentation code that doesn't impact the core learning objective about events.
4. fern/03-reference/baml_client/events.mdx:6
- Draft comment:
Replace the placeholder 'TODO' in the Info block with the actual release version information. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% While the comment identifies a real issue (a TODO placeholder), this is more of a documentation task than a code issue. The rules state not to make purely informative comments or ask for PR description updates. Documentation placeholders like this are typically handled through other processes. The TODO does need to be replaced at some point, and having it tracked in a PR comment could be helpful. Maybe this is actually important for documentation accuracy? While documentation accuracy is important, PR comments aren't the right place to track documentation TODOs. This should be handled through documentation review processes or issue tracking. Delete the comment. Documentation placeholders should be handled through documentation processes, not PR comments.
5. fern/docs.yml:414
- Draft comment:
New navigation entries for 'Runtime Events' have been added. Please verify that the paths and slugs (e.g., 'events') are accurate and consistent across the guides and reference sections. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%The comment is asking the PR author to verify the accuracy and consistency of paths and slugs, which falls under asking the author to double-check things. This violates the rules.
Workflow ID: wflow_Fs2iZPqn8UexjEuj
You can customize 
| results to your app’s users, or to debug a complex workflow combining multiple | ||
| LLM calls. | ||
|
|
||
| BAML makes this possible though an event system that connects variables in your |
There was a problem hiding this comment.
Typo: The sentence reads "BAML makes this possible though an event system...". Consider replacing "though" with "through".
Suggested change
| BAML makes this possible though an event system that connects variables in your | |
| BAML makes this possible through an event system that connects variables in your |
|
|
||
| 1. **Separate Thread** To avoid interfering with the rest of your BAML code, | ||
| callbacks are run concurrently in a separate execution thread. | ||
| 2. Events are meant for local tracking. If you asign a value to a new (non- |
There was a problem hiding this comment.
Typo: "asign" should be "assign".
Suggested change
| 2. Events are meant for local tracking. If you asign a value to a new (non- | |
| 2. Events are meant for local tracking. If you assign a value to a new (non- |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
imalsogreg
force-pushed
the
greg/emit-docs
branch
from
cbd8826 to
589e6e1
Compare
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
imalsogreg
had a problem deploying
to
boundary-tools-dev
GitHub Actions
Failure
There was a problem hiding this comment.
Caution
Changes requested ❌
Reviewed 589e6e1 in 2 minutes and 48 seconds. Click for details.
- Reviewed
777lines of code in3files - Skipped
0files when reviewing. - Skipped posting
5draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. fern/01-guide/05-baml-advanced/runtime-events.mdx:295
- Draft comment:
Consider adding a newline at the end of the file for POSIX compliance. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% While POSIX compliance for file endings is a real thing, this is an extremely minor issue that would be automatically handled by most editors and build systems. It doesn't affect functionality or readability. The rules state not to make comments that are obvious or unimportant. Missing newlines at end of file can cause issues with some tools and is considered a best practice by many. Some build systems will fail without it. While technically correct, this is exactly the kind of minor issue that should be handled by automated tooling rather than manual review comments. It adds noise to the review without providing meaningful value. Delete this comment as it is too minor and would be better handled by automated tooling.
2. fern/03-reference/baml_client/events.mdx:6
- Draft comment:
Replace 'TODO' in the info section with the correct version/release details. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%This comment is asking the PR author to update the PR description or similar information, which is against the rules. It doesn't provide a specific code suggestion or ask for a test to be written. Therefore, it should be removed.
3. fern/03-reference/baml_client/events.mdx:444
- Draft comment:
Consider adding a newline at the end of the file for consistency. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =20%<= threshold50%The comment suggests adding a newline at the end of the file for consistency. This is a common practice in coding standards to ensure consistency across files. However, it is not a critical issue and does not directly impact the functionality of the code. The comment is more of a suggestion for style consistency rather than a necessary change. According to the rules, purely informative comments should be removed, and this comment falls into that category.
4. fern/docs.yml:415
- Draft comment:
New 'Runtime Events' navigation entries have been added. Please verify that the paths and slugs (e.g. for guide and reference) are correct and consistent with the rest of the documentation. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%The comment is asking the PR author to verify paths and slugs, which falls under asking them to double-check things. This violates the rule against asking the author to confirm or ensure things are correct.
5. fern/01-guide/05-baml-advanced/runtime-events.mdx:14
- Draft comment:
Typo: Consider replacing 'though' with 'through' in the line "BAML makes this possible though an event system...". - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% While this is a real typo, the rules state we should not make purely informative comments. Typo fixes, while helpful, are not critical code changes that require attention in a PR review. This is more of an editorial comment than a technical issue. The typo does affect readability slightly, and fixing it would improve documentation quality. Maybe documentation should be held to different standards than code? The rules are clear that we should only comment when there is clearly a code change required. Documentation typos, while worth fixing, don't meet this threshold. The comment should be removed as it's a minor documentation issue that doesn't require immediate attention in the PR review process.
Workflow ID: wflow_MhW5TsJICVwTK6MC
You can customize
| --- | ||
|
|
||
| <Info> | ||
| This feature was added in TODO |
There was a problem hiding this comment.
Replace 'TODO' with the appropriate version/release information in the section.
Suggested change
| This feature was added in TODO | |
| This feature was added in v1.2.3 |
| results to your app’s users, or to debug a complex workflow combining multiple | ||
| LLM calls. | ||
|
|
||
| BAML makes this possible though an event system that connects variables in your |
There was a problem hiding this comment.
Typo: Change 'though' to 'through' in "BAML makes this possible though an event system...".
Suggested change
| BAML makes this possible though an event system that connects variables in your | |
| BAML makes this possible through an event system that connects variables in your |
| <Tab title="Python" language="python"> | ||
| ```python | ||
| # app.py | ||
| from baml_client.sync_client import { b } |
There was a problem hiding this comment.
In the Python example, remove the curly braces around b in the import. It should be: from baml_client.sync_client import b.
Suggested change
| from baml_client.sync_client import { b } | |
| from baml_client.sync_client import b |
|
|
||
| 1. **Separate Thread** To avoid interfering with the rest of your BAML code, | ||
| callbacks are run concurrently in a separate execution thread. | ||
| 2. Events are meant for local tracking. If you asign a value to a new (non- |
There was a problem hiding this comment.
Typo: "asign" should be corrected to "assign".
Suggested change
| 2. Events are meant for local tracking. If you asign a value to a new (non- | |
| 2. Events are meant for local tracking. If you assign a value to a new (non- |
imalsogreg
force-pushed
the
greg/emit-docs
branch
from
589e6e1 to
492828d
Compare
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
imalsogreg
temporarily deployed
to
boundary-tools-dev
GitHub Actions
Inactive
|
🌿 Preview your docs: https://boundary-preview-a2199030-497b-4c25-89af-588942a18b77.docs.buildwithfern.com |
There was a problem hiding this comment.
Caution
Changes requested ❌
Reviewed 492828d in 2 minutes and 4 seconds. Click for details.
- Reviewed
777lines of code in3files - Skipped
0files when reviewing. - Skipped posting
8draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. fern/01-guide/05-baml-advanced/runtime-events.mdx:165
- Draft comment:
The in-code marker '<-***' in the comment looks unclear. Consider removing or clarifying this annotation. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 10% vs. threshold = 50% The "<-***" marker is part of a documentation example showing how event tracking works. The marker helps connect related pieces of code to explain the feature. While unconventional, it serves a pedagogical purpose in this documentation context. The alternative suggestion would remove this connection. The marker is non-standard and could be confusing at first glance. There might be clearer ways to connect related code sections in documentation. However, this is documentation, not production code, and the marker effectively draws attention to connected concepts. The benefit of connecting related code outweighs the minor stylistic concern. The marker serves a useful purpose in the documentation context and should be kept.
2. fern/03-reference/baml_client/events.mdx:6
- Draft comment:
Replace placeholder 'TODO' with the actual version/release in the Info block. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% While the comment identifies a real issue (a TODO placeholder), this type of documentation placeholder is typically handled during the documentation review process, not during code review. It's more of an editorial comment than a code issue. Additionally, the comment suggests a specific version (v1.2.3) without clear evidence that this is the correct version. The TODO does need to be replaced at some point, and catching it early could be helpful. Maybe this is actually an important part of the code review process for this team? Documentation TODOs are better handled in documentation-specific reviews or by technical writers. The suggested version number appears to be made up, which could cause more confusion. Delete the comment as it's more appropriate for a documentation review than a code review.
3. fern/docs.yml:413
- Draft comment:
Runtime Events page added to the guides section. Verify that the path '01-guide/05-baml-advanced/runtime-events.mdx' is correct. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%The comment is asking the PR author to verify the path of a newly added file. This falls under asking the author to confirm or double-check something, which is against the rules. Therefore, this comment should be removed.
4. fern/docs.yml:695
- Draft comment:
Runtime Events page is added to the reference section with slug 'events'. Verify that the slug and path '03-reference/baml_client/events.mdx' are correct. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%The comment is asking the PR author to verify the correctness of the slug and path, which is against the rules. It doesn't provide a specific suggestion or point out a clear issue with the code.
5. fern/01-guide/05-baml-advanced/runtime-events.mdx:14
- Draft comment:
Typo: "though" should be "through" in the sentence "BAML makes this possible though an event system...". - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% While this is a real typo, our rules say we should focus on code changes and logic issues, not purely informative comments. This is a documentation file and the typo is minor - it doesn't affect understanding. The rules emphasize focusing on code quality and logic issues, not editorial fixes. The typo does affect readability slightly and it's a very clear, objective fix. Documentation quality could be considered important. While documentation quality matters, the rules explicitly state to focus on code changes and logic issues. This is a minor editorial fix that doesn't impact functionality. Delete this comment as it focuses on a minor documentation typo rather than code or logic issues.
6. fern/01-guide/05-baml-advanced/runtime-events.mdx:31
- Draft comment:
Typo in comment: "its what was found there for our marketing site." might be intended as "it's what was found there for our marketing site." (adding the missing apostrophe). - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% The rules state not to make purely informative comments. This is a minor grammatical issue in documentation/example code that doesn't affect functionality. The meaning is still clear even with the grammatical error. This seems like the kind of nitpicky comment we want to avoid. Could incorrect grammar in documentation confuse non-native English speakers? Could this affect the professionalism of the documentation? While professional documentation is important, this minor grammatical issue doesn't significantly impact readability or understanding. The rules specifically discourage purely informative comments that don't require code changes. Delete this comment as it's purely informative and doesn't affect code functionality or clarity.
7. fern/01-guide/05-baml-advanced/runtime-events.mdx:292
- Draft comment:
Typo: "asign" should be "assign" in the sentence "If you asign a value...". - Reason this comment was not posted:
Marked as duplicate.
8. fern/03-reference/baml_client/events.mdx:6
- Draft comment:
The line contains placeholder text 'TODO' ("This feature was added in TODO"). Consider replacing it with the appropriate version or release information before merging. - Reason this comment was not posted:
Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 0% vs. threshold = 50% This is a new file being added, and the TODO is part of the changed content. The comment is about ensuring documentation accuracy and completeness. However, asking authors to fill in TODOs is not one of our core review objectives - we're focused on code quality and correctness issues. The version number could be important for users to know when this feature became available. But we don't know if v0.7.0 is actually correct. While version info is useful, managing TODOs and documentation completeness is outside the scope of our automated review. This should be handled by the documentation review process. Delete this comment as it's about documentation completeness rather than code quality or correctness.
Workflow ID: wflow_DM3OWvrdIHMpjs0r
You can customize
| --- | ||
|
|
||
| <Info> | ||
| This feature was added in TODO |
There was a problem hiding this comment.
Replace placeholder 'TODO' with the actual version or release in the Info block.
Suggested change
| This feature was added in TODO | |
| This feature was added in v1.2.0 |
| results to your app’s users, or to debug a complex workflow combining multiple | ||
| LLM calls. | ||
|
|
||
| BAML makes this possible though an event system that connects variables in your |
There was a problem hiding this comment.
Possible typo: 'though' should likely be 'through' in the sentence describing the event system.
Suggested change
| BAML makes this possible though an event system that connects variables in your | |
| BAML makes this possible through an event system that connects variables in your |
|
|
||
| 1. **Separate Thread** To avoid interfering with the rest of your BAML code, | ||
| callbacks are run concurrently in a separate execution thread. | ||
| 2. Events are meant for local tracking. If you asign a value to a new (non- |
There was a problem hiding this comment.
Typo detected: 'asign' should be corrected to 'assign' in the explanation of local tracking.
Suggested change
| 2. Events are meant for local tracking. If you asign a value to a new (non- | |
| 2. Events are meant for local tracking. If you assign a value to a new (non- |
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.
Draft documentation for the event system.
Important
Adds documentation for BAML runtime events, detailing event tracking in workflows with examples and updates navigation to include these docs.
runtime-events.mdxtofern/01-guide/05-baml-advanced/for guiding users on using runtime events in BAML workflows.events.mdxtofern/03-reference/baml_client/detailing event types likeVarEventandBlockEvent.docs.ymlto include new pages under "Runtime Events" in both guide and reference sections.This description was created by
for 492828d. You can customize this summary. It will automatically update as commits are pushed.