fix(jsdocs): solve all lint warnings in project

[rinaok]

Waiting for #110

[codecov]

Codecov Report

Merging #869 (c451ea8) into main (d61b119) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##              main      #869    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files          123       194    +71     
  Lines         1562      2149   +587     
  Branches       108       130    +22     
==========================================
+ Hits          1562      2149   +587     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...omponents/src/lib/accordion-item/accordion-item.ts	100.00% <ø> (ø)
...components/src/lib/accordion/accordion.template.ts	100.00% <ø> (ø)
libs/components/src/lib/accordion/accordion.ts	100.00% <ø> (ø)
...ents/src/lib/action-group/action-group.template.ts	100.00% <ø> (ø)
...bs/components/src/lib/action-group/action-group.ts	100.00% <ø> (ø)
libs/components/src/lib/badge/badge.ts	100.00% <ø> (ø)
libs/components/src/lib/banner/banner.ts	100.00% <ø> (ø)
...ponents/src/lib/breadcrumb-item/breadcrumb-item.ts	100.00% <ø> (ø)
...mponents/src/lib/breadcrumb/breadcrumb.template.ts	100.00% <ø> (ø)
libs/components/src/lib/breadcrumb/breadcrumb.ts	100.00% <ø> (ø)
... and 178 more

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[yinonov]

please await #861 as this is a major change applying many files

[yinonov]

some of the ommited decorators like accessors (e.g. @public) are TSDoc related. we might need to go over them all and fix due to #818

[rinaok]

please await #861 as this is a major change applying many files

@yinonov Now after #861 is merged, can we merge this?

[yinonov]

please await #861 as this is a major change applying many files

@yinonov Now after #861 is merged, can we merge this?

it requires a very thorough review still. the pain point with this symptom relates to #110 (comment)

the optimal solution is, if tsdoc-lint was to enforce comments, to remove jsdoc-lint and use the tsdoc-lint instead

[rinaok]

please await #861 as this is a major change applying many files

@yinonov Now after #861 is merged, can we merge this?

it requires a very thorough review still. the pain point with this symptom relates to #110 (comment)

the optimal solution is, if tsdoc-lint was to enforce comments, to remove jsdoc-lint and use the tsdoc-lint instead

@yinonov But you said that we should avoid at this point from tsdoc #110 (comment)

[yinonov]

Because of lint technical limitation not enforcing necessary comments. But if u already went through and added all, we can reconsider tsdoc lint.
It will do more, now that api-extractor generate meta data

[YonatanKra]

I think we can exempt test files (.spec|test.ts) from tsdoc linting rule.
What do you think @olaf-k ?

[yinonov]

As #110 expected to now redfine eslint rules, it might outdate the changes of this PR.

what worries me is the fact we are not that acquainted with TSDoc and how to use it to its extent

the general idea to automate and improve our workflow is to have comments populating to READMEs and from there to docs website

for web components interfaces, TSDoc lacks some features, of where custom-elements-manifests come into play.

1st, let's make 1, single component as perfect POC, have its doc generated automatically.

going over lots of files to fix without a solid understanding the result will probably buy us more debts

[olaf-k]

I think we can exempt test files (.spec|test.ts) from tsdoc linting rule. What do you think @olaf-k ?

my gut feeling would be "yes please!" or at least keep only rules that prevent readability issues (weird capitalization, mix tab/space, this sort of stuff)

[yinonov]

I think we can exempt test files (.spec|test.ts) from tsdoc linting rule. What do you think @olaf-k ?

my gut feeling would be "yes please!" or at least keep only rules that prevent readability issues (weird capitalization, mix tab/space, this sort of stuff)

aware of any such preceding practice?

[olaf-k]

aware of any such preceding practice?

following our chat: it makes sense to keep some formatting rules to keep the code clean and readable for team members and minimize commit noise, while removing strict rules (e.g., no empty functions) for test files.

[olaf-k]

Note that the default linting target uses nx's run-many to check all projects and thus skips warnings.

To get the warnings displayed you must either add --verbose to the linting target command or simple run it project by project (e.g., npx nx lint components).

At the time of writing, there are still 400+ warning messages from the components project, repeating ones from tsdoc complaining about jsdoc formatting.

[rinaok]

Note that the default linting target uses nx's run-many to check all projects and thus skips warnings.

To get the warnings displayed you must either add --verbose to the linting target command or simple run it project by project (e.g., npx nx lint components).

At the time of writing, there are still 400+ warning messages from the components project, repeating ones from tsdoc complaining about jsdoc formatting.

@olaf-k good catch! @YonatanKra

[olaf-k]

Seeing the diff, there's a bunch of comments that could use some cleanup, but that's beyond the scope of this PR.

.