Partial fix #14227 (Add checker documentation for truncLongCastAssignment and truncLongCastReturn) [skip ci]

[danmar]

No description provided.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[firewave]

Documenting the checkers is good but some notes on that:

• we should make sure that the code is actually valid
  • the code cannot be compiled as it lacks the includes. I understand that is done to make it more readable but it makes it harder to other people to take the code and reproduce the actual issue. That is also a common issue with the documentation of other code checkers.
• we should make sure the issues are actually caught (we do it for the samples which are now redundant)
  • see above
• it would be good to include the actual reported issue
• in some other pages it is hard to make out what was actually changed in the code. Adding a different comment might not be sufficient so it should probably have some highlighting as there might be subtle changes which can easily be missed if the fix requires more than one lie to be adjusted (might not be possible with Markdown and also wanting C++ highlighting).

Maybe the source should be provided as good/bad files as the samples and the *.md pages generated from those files (that could also include the expected output).

[danmar]

I think this is good feedback.

• I am not strongly against that we provide the #include options.
• Some syntax checking to ensure code examples are valid sounds good.
• Showing what message cppcheck writes for each sample sounds good.
• I am against that code examples are broken out into separate good/bad files I want to provide a single interface for the user. However I would not be against that good/bad files are extracted from the md files so users have a choice..

[firewave]

• I am against that code examples are broken out into separate good/bad files I want to provide a single interface for the user. However I would not be against that good/bad files are extracted from the md files so users have a choice..

The code should be within the Markdown and separately on the filesystem. But there should be only one place that code is being maintained it. If that is achieved via injection or extraction should probably not matter (unless we realize one of them is more convenient of course).

[danmar]

But there should be only one place that code is being maintained it.

yes