[comm-services-lib] Fix doctests
ClosedPublic
Actions

Authored by michal on Aug 21 2023, 6:02 AM.

Details

Reviewers

bartek
• patryk
• jon

Commits

rCOMMcd565aeb9012: [comm-services-lib] Fix doctests

Summary

We have some examples in services lib (which is great!) but when running cargo test in comm-services-lib they all fail. This diff improves the examples so they can also be run alongside tests.

Here is some more info about documentation tests: https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html

We can use /// # syntax to include utility code that allows the example to be run, but won't be visible when generating the docs/ hovering over the definition in IDE.

This all adds some verbosity, so if it's decided that it's not the best option we should at least add ignore so the examples aren't run/compiled when running cargo test

Test Plan

cargo test --all-features

Diff Detail

Repository

rCOMM Comm

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

michal created this revision.Aug 21 2023, 6:02 AM

Herald added subscribers: tomek, ashoat. · View Herald TranscriptAug 21 2023, 6:02 AM

Harbormaster returned this revision to the author for changes because remote builds failed.Aug 21 2023, 6:08 AM

Harbormaster failed remote builds in B21945: Diff 30137!

Rebase

michal edited the summary of this revision. (Show Details)Aug 21 2023, 9:42 AM

Harbormaster completed remote builds in B21959: Diff 30156.Aug 21 2023, 10:06 AM

michal requested review of this revision.Aug 21 2023, 10:06 AM

michal added a child revision: D8892: [services] Extract multipart handling logic to lib.Aug 21 2023, 10:34 AM

Okay, this is the one thing I hate about rust - these are MY comments and it shoul not be doctest's business unless I explicitly ask it for opinions.
Examples should be readable for us, for our use cases, I don't care about what doctest expects.

We can use /// # syntax to include utility code that allows the example to be run, but won't be visible when generating the docs/ hovering over the definition in IDE.

I don't care about running examples - it's useless when it comes to database/external services related code. I wrote these on purpose to be displayed in IDE when hovering.

This all adds some verbosity, so if it's decided that it's not the best option we should at least add ignore so the examples aren't run/compiled when running cargo test

Yeah, there should be an option to ignore this and tbh I'd prefer that

Cool, changed approach to just ignoring the examples

Harbormaster completed remote builds in B21988: Diff 30190.Aug 22 2023, 3:06 AM

michal added a parent revision: D8883: [backup] Use blob client.Aug 22 2023, 3:24 AM

bartek accepted this revision.Aug 22 2023, 3:49 AM

This revision is now accepted and ready to land.Aug 22 2023, 3:49 AM

Closed by commit rCOMMcd565aeb9012: [comm-services-lib] Fix doctests (authored by Michal Gniadek <michal.gniadek@swmansion.com>). · Explain WhyAug 25 2023, 9:40 AM

This revision was automatically updated to reflect the committed changes.

Michal Gniadek <michal.gniadek@swmansion.com> added a commit: rCOMMcd565aeb9012: [comm-services-lib] Fix doctests.