Skip to content

Add documentation for the SpaceBeforeCast sniff #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 13, 2023
Merged

Add documentation for the SpaceBeforeCast sniff #159

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9f44251
Add documentation for the SpaceBeforeCast sniff
rodrigoprimo Dec 12, 2023
c9c9b09
Minor improvements to the SpaceBeforeCast sniff documentation
rodrigoprimo Dec 13, 2023
1f90b17
Combine code examples into a single `<code_comparison>` block
rodrigoprimo Dec 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions src/Standards/Generic/Docs/Formatting/SpaceBeforeCastStandard.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<documentation title="Space Before Casts">
<standard>
<![CDATA[
Ensures there is exactly one space before a cast operator.
]]>
</standard>
<code_comparison>
<code title="Valid: Single space before a cast operator.">
<![CDATA[
$integer =<em> </em>(int) $string;
]]>
</code>
<code title="Invalid: No space before a cast operator.">
<![CDATA[
$integer =<em></em>(int) $string;
]]>
</code>
</code_comparison>
<code_comparison>
<code title="Valid: Single space before a cast operator.">
<![CDATA[
$c = $a +<em> </em>(int) $b;
]]>
</code>
<code title="Invalid: Multiple spaces before a cast operator.">
<![CDATA[
$c = $a +<em> </em>(int) $b;
]]>
</code>
Copy link
Member

@jrfnl jrfnl Dec 12, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As the valid code is essentially the same for both cases, I think it might be better to use a single <code_comparison> block, where the left side would have either just the one or both of the "valid" examples and the right side the two "invalid" examples.

Might also be good to vary the type casts used in the code samples a little as people could get the impression this is only about (int) type casts based on the current code samples.

Copy link
Contributor Author

@rodrigoprimo rodrigoprimo Dec 13, 2023 •
edited by jrfnl
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even though the valid code is essentially the same for both cases, I opted for this approach as it was the only way that I could find to have titles for the two different invalid codes to highlight that this sniff acts when there is no space and also when there are multiple spaces.

I think it might be better to use a single <code_comparison> block, where the left side would have either just the one or both of the "valid" examples and the right side the two "invalid" examples.

I might be missing something, but I was not able to find a way to have more than two <code> blocks inside a <code_comparison> block. Or is your suggestion that I combine both invalid examples in a single <code> block?

Might also be good to vary the type casts used in the code samples a little as people could get the impression this is only about (int) type casts based on the current code samples.

👍

Maybe the second example could be:

        <code title="Valid: Single space before a cast operator.">
        <![CDATA[
$c = $a . <em> </em>(string) $b;
        ]]>
        </code>
        <code title="Invalid: Multiple spaces before a cast operator.">
        <![CDATA[
$c = $a .<em>   </em>(string) $b;
        ]]>
        </code>

(I'm happy to adjust the example above and include it in the first <code_comparison> block depending on what you suggest as the best approach for the other topic that we are discussing in this thread)

Copy link
Member

@jrfnl jrfnl Dec 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There should only be two code blocks per code comparison, but a code block can contain multiple code samples.

If it clarifies things, you can use inline comments in the code sample to add some additional info, like so:

        <code title="Invalid: Multiple spaces before a cast operator.">
        <![CDATA[
// Too much space.
$c = $a +<em>   </em>(int) $b;
        ]]>
        </code>

Having said that, I don't really think those comments are needed in this case as "no space" and "too much space" both translate to "not using a single space", so a good description for the "invalid" case can cover both.

what you suggest as the best approach for the other topic that we are discussing in this thread

Which other topic ?

Copy link
Contributor Author

@rodrigoprimo rodrigoprimo Dec 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it clarifies things, you can use inline comments in the code sample to add some additional info, like so:

It's good to know that this is an option. Thanks.

Having said that, I don't really think those comments are needed in this case as "no space" and "too much space" both translate to "not using a single space", so a good description for the "invalid" case can cover both.

I just pushed 1f90b17 in which I combined both code examples into a single <code_comparison>, changed the second code example to use (string) instead of (int) and updated the title of the invalid case to mention both no space and multiple spaces.

what you suggest as the best approach for the other topic that we are discussing in this thread

Which other topic ?

Our conversation on whether to use one or two <code_comparison> blocks. I just wanted to make it explicit that with the example that I provided, I was not implying that we should continue to use two <code_comparison> blocks.

</code_comparison>
</documentation>