Improve model guide#515
Conversation
|
Bencher Report| Branch | elijah/model-docs-improve |
| Testbed | github-ubuntu-latest |
Click to view all benchmark results
| Benchmark | Latency | Benchmark Result milliseconds (ms) (Result Δ%) | Upper Boundary milliseconds (ms) (Limit %) |
|---|---|---|---|
| empty_router/empty_router | 📈 view plot 🚷 view threshold | 6.41 ms(+5.68%)Baseline: 6.07 ms | 7.37 ms (87.04%) |
| json_api/json_api | 📈 view plot 🚷 view threshold | 1.15 ms(+9.04%)Baseline: 1.06 ms | 1.26 ms (91.71%) |
| nested_routers/nested_routers | 📈 view plot 🚷 view threshold | 1.09 ms(+11.77%)Baseline: 0.97 ms | 1.15 ms (94.82%) |
| single_root_route/single_root_route | 📈 view plot 🚷 view threshold | 1.05 ms(+11.92%)Baseline: 0.94 ms | 1.11 ms (94.14%) |
| single_root_route_burst/single_root_route_burst | 📈 view plot 🚷 view threshold | 17.85 ms(+0.99%)Baseline: 17.68 ms | 21.08 ms (84.68%) |
Codecov Report✅ All modified and coverable lines are covered by tests.
Flags with carried forward coverage won't be shown. Click here to find out more. 🚀 New features to boost your workflow:
|
|
depends on cot-rs/cot-site#82 and cot-rs/cot-site#84 |
|
|
|
||
| ``` | ||
|
|
||
| ## Summary |
There was a problem hiding this comment.
Some pages have a Summary section while others don't. I'm not too sure which direction we'd want to go, but for the sake of consistency, do we require every page to have a Summary section? I, personally, am not a big fan, but I'm also indifferent if we have them or not
m4tx
left a comment
m4tx
left a comment
There was a problem hiding this comment.
Amazing stuff! There are some issues here and there - please make the changes before we can merge this.
Also, sometimes you put an additional newline after section headers, sometimes you do not - please make this consistent with the rest of the guides.
| #[derive(Debug, Clone)] | ||
| struct NewType(i32); | ||
|
|
||
| impl FromDbValue for NewType { |
There was a problem hiding this comment.
I'm not exactly happy with how closely tied this is to the specific database backend one can use. I would expect this to be changed in the future when we'll finally land the ORM refactor.
I think it's fine to keep it as-is because there's not much we can do about this for now, but just adding this as a general comment.
| struct MyProject; | ||
|
|
||
| impl Project for MyProject { | ||
| fn config(&self) -> cot::Result<ProjectConfig> { |
There was a problem hiding this comment.
I'm not sure if it's good to put this here. The side effect of such change is that after adding this code, the TOML config will be completely ignored, which might be not what user might want.
I'd suggest either mentioning this (something in the lines of "keep in mind that adding this code will cause the TOML config to be ignored for other config parameters as well"), or remove this section altogether.
| * PostgreSQL | ||
| * MySQL | ||
|
|
||
|
|
|
|
||
| As an alternative to setting the database configuration in the `TOML` file, you can also set it programmatically in the [`config`](trait@cot::project::Project#method.config) method of your project: | ||
|
|
||
|
|
| Saving a foreign key field is similar to saving a regular field. There are two variants of foreign key fields provided by cot: | ||
|
|
||
| ### `ForeignKey::Model` | ||
| This is the most common variant which allows you to save a foreign key field with a model instance. |
There was a problem hiding this comment.
It might be worth noting that the instance needs to be saved to the database first.
| } | ||
| ``` | ||
| The [`get`](struct@cot::db::query::Query#method.get) method (as well as the [`all`](struct@cot::db::query::Query#method.all) method which we'll see in the next section) are terminal query methods which are applied to the query object after filtering to retrieve the final results. | ||
| Also note that the [`get`](struct@cot::db::query::Query#method.get) method will return an error if the query returns more than one result. |
There was a problem hiding this comment.
This is not true at the moment, right? I think we should change the ORM's behavior to match this, but we shouldn't necessarily mention this right now.
2 participants
Restructure the Docs, starting with the model docs. I've improved the docs to mention a large number of features/functionalities we support. I've also split the docs to span across multiple pages in a subcategory, making it easier and nicer to follow. Currently, we have 2 pages (overview and queries) for Models. The overview section is a bit nuanced as it makes mention of the CotORM, setting up models, and configuring them.
There's also a section of Relationships which I believe deserves its own page once we have the M2M feature implemented(or we can still put this in its own page and show how to do this using an intermediate
throughModel).I would like to add another page for migrations, however, I'm keeping this PR ready at all times for review. Subsequent additions may or may not be included to this PR depending on when this gets merged
Related issue or discussion
Description
Type of change
Checklist
just test-all)just clippy)cargo fmt)