Skip to content

revamp user guides#732

Merged
OmarTawfik merged 2 commits intomainfrom
revamp-user-guide
Jan 10, 2024
Merged

revamp user guides#732
OmarTawfik merged 2 commits intomainfrom
revamp-user-guide

Conversation

@OmarTawfik
Copy link
Copy Markdown
Contributor

@OmarTawfik OmarTawfik commented Jan 9, 2024

  • Consolidate the examples between Rust and TypeScript, to make it easier to update them together moving forward.
  • Use the same names and examples between languages.
  • Move all API references to [concepts.md], and keep the how-tos strictly focused on code.
  • remove a lot of duplicate code between the different examples.
  • hide useless/repetitive code that is for testing/infra, and only include user-facing snippets.
  • Show previous/next links between guides, to make it easier to read them in order.
  • Remove some of the useless [index.md] files, making sure sidebar navigation lists the following (in-order):
    • Introduction
    • Concepts
    • Rust Examples
    • TypeScript Examples

Note: I suggest reviewing using infra watch mkdocs for this PR.

@OmarTawfik OmarTawfik requested a review from a team as a code owner January 9, 2024 14:02
@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Jan 9, 2024 •
edited
Loading

⚠️ No Changeset found

Latest commit: a29eb39

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@OmarTawfik OmarTawfik mentioned this pull request Jan 9, 2024
Merged
@OmarTawfik OmarTawfik force-pushed the revamp-user-guide branch 2 times, most recently from 937ddaa to f6fafc0 Compare January 9, 2024 14:17
github-merge-queue bot pushed a commit that referenced this pull request Jan 10, 2024
@OmarTawfik
add RuleNode.unparse() to the TypeScript API (#731)
3deaea2 
used in #732
Base automatically changed from add-unparse-napi to main January 10, 2024 10:49
@OmarTawfik
revamp user guides
98bc9fc 
- Consolidate the examples between Rust and TypeScript, to make it easier to update them together moving forward.
- Use the same names and examples between languages.
- Move all API references to [concepts.md], and keep the how-tos strictly focused on code.
- remove a lot of duplicate code between the different examples.
- hide useless/repetitive code that is for testing/infra, and only include user-facing snippets.
- Show previous/next links between guides, to make it easier to read them in order.
- Remove some of the useless [index.md] files, making sure sidebar navigation lists the following (in-order):
  - Introduction
  - Concepts
  - Rust Examples
  - TypeScript Examples

Note: I suggest reviewing using `infra watch mkdocs` for this PR.
@OmarTawfik OmarTawfik enabled auto-merge January 10, 2024 11:50
Xanewok
Xanewok suggested changes Jan 10, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@Xanewok Xanewok left a comment

Choose a reason for hiding this comment

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

Thanks for unifying some of the snippets and related files! Most of the changes look good to me but I'd like to improve readability when using some snippets and try to find a better place for/reshuffle the API section.

@OmarTawfik OmarTawfik requested a review from Xanewok January 10, 2024 15:20
Xanewok
Xanewok approved these changes Jan 10, 2024
View reviewed changes
Copy link
Copy Markdown
Contributor

@Xanewok Xanewok left a comment

Choose a reason for hiding this comment

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

Great job! I'd probably come back and polish the concepts but this improves status quo, so let's land this 🎉

documentation/public/user-guide/concepts.md
Comment on lines +6 to +18
## Language Versions

To use Slang, you start by initializing a `Language` object with a specific version of the language.
The earliest Solidity version we support is `0.4.11`, and we plan on supporting all future versions as they are released.

From a `Language` object, you can analyze any source text according to the rules of that specific version.
Providing an accurate language version is important, as it affects the shape of the syntax tree, and possible errors produced.
You can use the `Language::getSupportedVersions()` API to get a list of all supported versions for the current Slang release.

The `Language::parse()` API is the main entry point for the parser, and to generate concrete syntax trees (CSTs) that can be used for further analysis.
Each `parse()` operation accepts the input source code, and a `RuleKind` variant.
This allows callers to parse entire source files (`RuleKind::SourceUnit`), individual contracts (`RuleKind::ContractDefinition`),
methods (`RuleKind::FunctionDefinition`), or any other syntax nodes.
Copy link
Copy Markdown
Contributor

@Xanewok Xanewok Jan 10, 2024

Choose a reason for hiding this comment

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

I am still not sold on this, given how much there's code/blocks here and in the CST Cursors section and supporting multiple versions as an idea/concept is explained already in User Guide > Introduction.

I don't think this is also a good place to list all different kinds of node relationships the cursor can jump to (to give an example what I mean by a lot of code), but given how this PR improves multiple other different things, I don't want to block on this and we can try to make it clearer in a follow-up.

@OmarTawfik OmarTawfik added this pull request to the merge queue Jan 10, 2024
Merged via the queue into main with commit 2333d73 Jan 10, 2024
@OmarTawfik OmarTawfik deleted the revamp-user-guide branch January 10, 2024 15:58
@OmarTawfik OmarTawfik linked an issue Feb 13, 2024 that may be closed by this pull request
missing architecture docs #534
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@Xanewok Xanewok Xanewok approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

missing architecture docs

2 participants

@OmarTawfik @Xanewok