boa icon indicating copy to clipboard operation
boa copied to clipboard

Published 20 hours ago • verified publisher icon boa-dev

Add code examples for `boa_interner`

Open jedel1043 opened this issue 2 years ago • 12 comments

The boa_interner crate has an allow(rustdoc::missing_doc_code_examples) on its root. Ideally, this crate should have some usage snippets on every pub function.

jedel1043 avatar Oct 10 '22 18:10 jedel1043

Can I pick this up?

Joymfl avatar Oct 18 '22 00:10 Joymfl

Can I pick this up?

Assigned!

jedel1043 avatar Oct 18 '22 00:10 jedel1043

Hey, currently I'm looking at how the pub functions are being used in the boa_interner/src/tests.rs and then documenting code examples for the same, but I see more functions that aren't being used in the tests. Any tips on how to understand and document them?

Joymfl avatar Oct 18 '22 21:10 Joymfl

Most of the public functions have usages inside boa_interner itself, so you could start from that. I think the only unused functions are Interner::new and Interner::with_capacity, for which you can adapt the examples of Vec::new and Vec::with_capacity.

jedel1043 avatar Oct 18 '22 21:10 jedel1043

Sounds good 👍🏾 . I'll try that and get back to you

Joymfl avatar Oct 18 '22 22:10 Joymfl

@Joymfl , any update on this ?

postmeback avatar Jun 30 '23 09:06 postmeback

I don't think this issue should be closed, since the related PR added a couple of tests, but no examples in the documentation of the interner.

Razican avatar Aug 06 '23 20:08 Razican

I don't think this issue should be closed, since the related PR added a couple of tests, but no examples in the documentation of the interner.

Can you give me an reference, where should I add the documentation ?

@jedel1043 @Razican

postmeback avatar Aug 07 '23 05:08 postmeback

Hi, Can i get any assistance on the above comment, please?

postmeback avatar Oct 03 '23 09:10 postmeback

Hi @postmeback, sorry for not writing here!

I was checking the code, and in fact, the mentioned lint is unstable (https://github.com/rust-lang/rust/issues/101730). You could in theory enable it by adding #![feature(rustdoc_missing_doc_code_examples)] and #![warn(rustdoc::missing_doc_code_examples)] in lib.rs in boa_interner, and then run cargo +nightly doc to get the relevant warnings.

This can help you get the warnings on where some usage examples need to be added in the API. boa_interner was selected for this since its public API is small enough.

For each warning, the idea is to add some code examples in the doc comments, that show how to use it.

Razican avatar Oct 03 '23 17:10 Razican

I followed your steps, I did not get any warnings in the boa_interner folder.

image

Requesting you to provide your feedback on this. :)

postmeback avatar Oct 07 '23 17:10 postmeback

I followed your steps, I did not get any warnings in the boa_interner folder.

Saw that you ran cargo +nightly fmt. You would need to run cargo +nightly doc instead to see the warnings.

jedel1043 avatar Oct 07 '23 17:10 jedel1043