feat: propagate doc comments on flags and arguments to `--help/-h` + structs derive refactor #26

dj8yfo · 2024-12-12T22:36:54Z

the crux of the pr is 0c3ce3a
and 912744d

the rest is some refactoring and splitting big chunks of code into smaller and nested modules/functions

the changes to the logic of derives aren't many and are well summarised by
the following list of commits with snapshot differences
from the same tests as added to master branch in
https://github.com/dj8yfo/interactive-clap/commits/backporting_tests_into_master/ branch:

test_simple_struct => eb4b124 (fragments reorder)
test_simple_struct_with_named_arg => ddb3891 (fragments reorder)
test_doc_comments_propagate => 6461299 (doc comments propagated, clap(verbatim_doc_comment) propagated, fragments reordered)
test_simple_enum => no change
test_simple_enum_with_strum_discriminants => no change
also a bug was found when integrating new functionality:
- new test
- snapshot change in InteractiveClap derive, test passing
- input change for 2nd stage derive of ToCliArgs resulted in test failing

second (or 3rd) sub-summary mentions 2 commits 382cc33, 3db17e1 which made
a testing step automatic and not requiring to manually copy-paste a fragment
from snapshot generated with first test assertion.
No snapshots changed as result of these latter 2 commits.

dj8yfo · 2024-12-12T22:50:54Z

introspect feature can be used to debug how derive proc macros work similar to the following:

# interactive-clap-derive folder
cargo test test_doc_comments_propagate --features introspect -- --nocapture 
# from repo root
cargo run --example struct_with_subargs --features interactive-clap-derive/introspect

…nd `long_help` Add this functionality in commented form

dj8yfo · 2025-01-06T20:09:29Z

this is still draft, pending some small work on top of it

…ntributor)

…nt_of_to_cli_trait module

… to derives::interactive_clap::structs::cli_variant_of_to_cli_trait::field

…ant_of_to_cli_trait`

…g from `master`

…with_named_arg`

… `master`

…ropagate`

…ants

…riminants from `master`

…n tests

dj8yfo · 2025-02-06T23:05:01Z

@race-of-sloths include

race-of-sloths · 2025-02-06T23:05:35Z

@dj8yfo Thank you for your contribution! Your pull request is now a part of the Race of Sloths!
Do you want to apply for monthly streak? Get 8+ score for a single PR this month and receive boost for race-of-sloths!

Current status: waiting for scoring

We're waiting for maintainer to score this pull request with @race-of-sloths score [0,1,2,3,5,8,13] command. Alternatively, autoscoring [1,2] will be applied for this pull request

What is the Race of Sloths

Race of Sloths is a friendly competition where you can participate in challenges and compete with other open-source contributors within your normal workflow

For contributors:

Tag @race-of-sloths inside your pull requests
Wait for the maintainer to review and score your pull request
Check out your position in the Leaderboard
Keep weekly and monthly streaks to reach higher positions
Boast your contributions with a dynamic picture of your Profile

For maintainers:

Score pull requests that participate in the Race of Sloths and receive a reward
Engage contributors with fair scoring and fast responses so they keep their streaks
Promote the Race to the point where the Race starts promoting you
Grow the community of your contributors

Feel free to check our website for additional details!

Bot commands

For contributors
- Include a PR: @race-of-sloths include to enter the Race with your PR
For maintainers:
- Invite contributor @race-of-sloths invite to invite the contributor to participate in a race or include it, if it's already a runner.
- Assign points: @race-of-sloths score [1/2/3/5/8/13] to award points based on your assessment.
- Reject this PR: @race-of-sloths exclude to send this PR back to the drawing board.
- Exclude repo: @race-of-sloths pause to stop bot activity in this repo until @race-of-sloths unpause command is called

akorchyn

I'll return back to it a bit later. Hard to keep up :)

interactive-clap-derive/src/debug.rs

akorchyn · 2025-02-07T13:18:47Z

interactive-clap-derive/src/derives/interactive_clap/common_methods/choose_variant.rs

            if attr.path.is_ident("strum_discriminants") {
                for attr_token in attr.tokens.clone() {
                    if let proc_macro2::TokenTree::Group(group) = attr_token {
-                        if &group.stream().to_string() == "derive(EnumMessage, EnumIter)" {
+                        let group_stream_no_whitespace =
+                            group.stream().to_string().replace(" ", "");


maybe split_whitespaces and then collect, or something like that.
maybe some weirdo uses tabs or something like that and ignores fmt.

akorchyn · 2025-02-07T13:21:30Z

interactive-clap-derive/src/derives/interactive_clap/mod.rs

 use proc_macro2::{Span, TokenStream};
 use proc_macro_error::abort_call_site;
 use quote::{quote, ToTokens};
 use syn;

-use crate::LONG_VEC_MUTLIPLE_OPT;
+#[cfg(test)]


I think cfg test module should be at the end of the file

akorchyn · 2025-02-07T13:26:12Z

interactive-clap-derive/src/derives/interactive_clap/mod.rs

-    }
-}
+/// these are common methods, reused for both the [structs] and `enums` derives
+pub(super) mod common_methods;


should be at the top of the file

akorchyn · 2025-02-07T13:30:15Z

interactive-clap-derive/src/derives/interactive_clap/mod.rs

    }
+
+    #[doc = include_str!("../../../docs/structs_to_cli_trait_docstring.md")]
+    pub(crate) mod to_cli_trait;


Same here, move them to the top.

Can you move the docs back to this file (or to the file itself)? I think it's crucial to keep it here, as it's mostly for internal devs, and it's not pleasant to search for a separate file.

As a developer, I never build docs for my crate just to understand the logic.

This is pretty important point for me

yeap, ok
the thing is really convoluted to understand, that's why the doc.
as a reference point to return later to later, when context will be forgotten.
if it helps me navigate, maybe it'll help someone else, though the latter is unlikely

akorchyn · 2025-02-07T13:36:08Z

interactive-clap-derive/docs/clap_enum_for_named_arg_docstring.md

@@ -0,0 +1,27 @@
+derive of helper enum for structs with `#[interactive_clap(named_arg)]` on fields


It's internal doc, so I would better keep it with the code at the level with the code

akorchyn · 2025-02-07T13:40:27Z

interactive-clap-derive/src/derives/interactive_clap/structs/clap_for_named_arg_enum.rs

+    fields
+        .iter()
+        .find_map(|field| field_transform(name, field))
+        .unwrap_or(quote!())


I know it was before, but should we put here that debug macro? to indicate that we ccouldn't transform?

i don't quite understand the suggestion.
if the dbg_cond! macro is implied, i only added it to the paths i had trouble with figuring out for adding tests/looking at a bug or just generally figuring them out.
there are many more possible paths to cover with debug statements, i think there're at least 100x more of them.

i believe this module was a product of extracting this chunk of code
https://github.com/near-cli-rs/interactive-clap/pull/26/files#diff-f36bdc4e97c2bde45b6fdb5764c7a15faf2ab71c0fcd30d123dac570724594c0L147-L192 .
(Github UI doesn't seem to be capable of autoexpanding this link to the exact chunk, you would have to scroll to interactive-clap-derive/src/derives/interactive_clap/mod.rs file and click Load file button to be able to see the exact chunk, without clicking any other links or buttons, or Github will overwrite the info about chunk in URL).

added link to the chunk in the pr's base branch https://github.com/near-cli-rs/interactive-clap/blob/master/interactive-clap-derive/src/derives/interactive_clap/mod.rs#L147-L192 , this appears to work straightforwardly.

akorchyn · 2025-02-07T13:46:01Z

...ap-derive/src/derives/interactive_clap/structs/to_cli_trait/clap_parser_trait_adapter/mod.rs

@@ -0,0 +1,26 @@
+use proc_macro2::TokenStream;


maybe we can just clap_parser_trait_adapter.rs

we don't have any submodules

akorchyn · 2025-02-07T14:02:56Z

Can you create a patch for near-cli-rs and check that it's starting speed is sufficient and not struggle as Vlad described on a call?

dj8yfo · 2025-02-07T14:34:46Z

@akorchyn patch was created near/near-cli-rs#444 , the starting lag is (visually) the same as in main

src/lib.rs

examples/struct_with_subargs.rs

...rc/tests/snapshots/interactive_clap_derive__tests__test_simple_struct__vec_multiple_opt.snap

Co-authored-by: Artur Yurii Korchynskyi <[email protected]>

dj8yfo marked this pull request as ready for review December 13, 2024 18:17

frol requested a review from FroVolod December 22, 2024 19:29

dj8yf0μl added 5 commits January 6, 2025 22:05

commented: add propagate doc attributes for clap's derive of help a…

251dfce

…nd `long_help` Add this functionality in commented form

test: add test_doc_comments_propagate

ae76568

uncomment: propagating doc comments attributes

0c3ce3a

chore: add dbg_cond! macro

e02529d

chore: add passthrough of verbatim_doc_comment attribute to clap

912744d

dj8yfo marked this pull request as draft January 6, 2025 20:07

merge: master into this

1d16e9b

dj8yfo force-pushed the propagate_doc_comments_on_flags branch from a6406da to 1d16e9b Compare January 6, 2025 20:30

dj8yf0μl added 11 commits January 6, 2025 22:41

ci: fix clippy

451e7e3

Merge branch 'master' into propagate_doc_comments_on_flags

d1d8e06

Merge branch 'master' into propagate_doc_comments_on_flags

7ef647b

test: add 2 simple tests for enums

19c9d77

test: add strum_discriminants(strum attributes to enum test

15bc985

test: add doc comment over enum for test with strum-messages

9de4082

doc: check nice publish with private items

e28aee7

doc: add doc-string about dbg_cond! macro

b831cbc

ci: resolve near-cli-rs#34

1344f02

chore: add rust-toolchain.toml (autoinstalls rust-analyzer for any co…

222ee83

…ntributor)

chore: extract logic to derives::interactive_clap::structs::cli_varia…

709e4bc

…nt_of_to_cli_trait module

dj8yfo mentioned this pull request Jan 9, 2025

ci: add cargo doc job #34

Open

dj8yf0μl added 5 commits January 9, 2025 16:35

chore: move derives::interactive_clap::methods::cli_field_type module…

13e6f2a

… to derives::interactive_clap::structs::cli_variant_of_to_cli_trait::field

chore: change field_type return type from TokenStream -> syn::Type

63dea02

chore: group together derive items, that belong to `structs::cli_vari…

18ae13e

…ant_of_to_cli_trait`

chore: move impl From<#name> for #cli_name derive into submodule

99d1c65

chore: move impl #name (clap::Parser adapter block) into submodule

4d84f7c

dj8yfo force-pushed the propagate_doc_comments_on_flags branch from 2008066 to f1ad05f Compare January 24, 2025 18:09

dj8yf0μl added 2 commits February 4, 2025 22:39

testcode + snapshot change of master -> (pr) for test_simple_struct

eb4b124

test: add context for why test_bug_fix_of_to_cli_args_derive was added

7c296a4

dj8yfo force-pushed the propagate_doc_comments_on_flags branch from b1e5faa to 7c296a4 Compare February 4, 2025 20:39

dj8yf0μl added 13 commits February 4, 2025 22:47

test: ignore snapshots for test_simple_struct_with_named_arg

65f6fb7

test: forwardport test+snapshots for test_simple_struct_with_named_ar…

ccfbb2c

…g from `master`

testcode + snapshot change of master -> (pr) for `test_simple_struct_…

ddb3891

…with_named_arg`

test: ignore test+snapshots for test_doc_comments_propagate

632ac61

test: forwardport test+snapshots for test_doc_comments_propagate from…

26ee82d

… `master`

testcode + snapshot change of master -> (pr) for `test_doc_comments_p…

6461299

…ropagate`

test: ignore test+snapshots for test_simple_enum

840636a

test: forwardport test+snapshots for test_simple_enum from master

5dc36c1

test: ignore test+snapshots for test_simple_enum_with_strum_discrimin…

7e1ec80

…ants

test: forwardport test+snapshots for test_simple_enum_with_strum_disc…

d87ee59

…riminants from `master`

test: unify 2-step variables names in derive tests

985a465

chore: extract cli_variant_struct derive module for reusability in tests

382cc33

test: add to_cli_args_structs_test_bridge module for automatic step i…

3db17e1

…n tests

dj8yfo mentioned this pull request Feb 5, 2025

feat: embed docs for flags/arguments for -h/--help near/cargo-near#304

Open

dj8yfo marked this pull request as ready for review February 6, 2025 23:02

dj8yfo requested review from akorchyn and PolyProgrammist as code owners February 6, 2025 23:02

akorchyn requested changes Feb 7, 2025

View reviewed changes

akorchyn reviewed Feb 7, 2025

View reviewed changes

src/lib.rs Outdated Show resolved Hide resolved

examples/struct_with_subargs.rs Show resolved Hide resolved

...rc/tests/snapshots/interactive_clap_derive__tests__test_simple_struct__vec_multiple_opt.snap Show resolved Hide resolved

suggestion ui: Update src/lib.rs

f85e437

Co-authored-by: Artur Yurii Korchynskyi <[email protected]>

dj8yfo marked this pull request as draft February 10, 2025 15:33

dj8yf0μl added 2 commits February 10, 2025 19:18

review: addresses near-cli-rs#26 (comment)

87848e4

review: silence a clippy lint too near-cli-rs#26 (comment)

bc0a363

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: propagate doc comments on flags and arguments to `--help/-h` + structs derive refactor #26

feat: propagate doc comments on flags and arguments to `--help/-h` + structs derive refactor #26

dj8yfo commented Dec 12, 2024 •

edited

Loading

dj8yfo commented Dec 12, 2024

dj8yfo commented Jan 6, 2025

dj8yfo commented Feb 6, 2025

race-of-sloths commented Feb 6, 2025

akorchyn left a comment

akorchyn Feb 7, 2025

akorchyn Feb 7, 2025

akorchyn Feb 7, 2025

akorchyn Feb 7, 2025

akorchyn Feb 7, 2025

dj8yfo Feb 7, 2025 •

edited

Loading

akorchyn Feb 7, 2025

akorchyn Feb 7, 2025

dj8yfo Feb 10, 2025 •

edited

Loading

dj8yfo Feb 10, 2025 •

edited

Loading

dj8yfo Feb 10, 2025

akorchyn Feb 7, 2025

akorchyn commented Feb 7, 2025 •

edited

Loading

dj8yfo commented Feb 7, 2025

		@@ -0,0 +1,27 @@
		derive of helper enum for structs with `#[interactive_clap(named_arg)]` on fields

feat: propagate doc comments on flags and arguments to --help/-h + structs derive refactor #26

Are you sure you want to change the base?

feat: propagate doc comments on flags and arguments to --help/-h + structs derive refactor #26

Conversation

dj8yfo commented Dec 12, 2024 • edited Loading

dj8yfo commented Dec 12, 2024

dj8yfo commented Jan 6, 2025

dj8yfo commented Feb 6, 2025

race-of-sloths commented Feb 6, 2025

akorchyn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dj8yfo Feb 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dj8yfo Feb 10, 2025 • edited Loading

Choose a reason for hiding this comment

dj8yfo Feb 10, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

akorchyn commented Feb 7, 2025 • edited Loading

dj8yfo commented Feb 7, 2025

feat: propagate doc comments on flags and arguments to `--help/-h` + structs derive refactor #26

feat: propagate doc comments on flags and arguments to `--help/-h` + structs derive refactor #26

dj8yfo commented Dec 12, 2024 •

edited

Loading

dj8yfo Feb 7, 2025 •

edited

Loading

dj8yfo Feb 10, 2025 •

edited

Loading

dj8yfo Feb 10, 2025 •

edited

Loading

akorchyn commented Feb 7, 2025 •

edited

Loading