Document AAA06 resolution for hash-comments with no arrange block

[jamescooke]

Current behaviour

The following test gives an AAA06 comment in Act block:

def test() -> None:
    # NOTE: the most interesting thing about this test is this comment
    result = 1 + 1

    assert result == 2

The documentation isn't clear about this scenario or how to fix it.

The reason this is a valid AAA06 scenario is because writing the hash-comment above the act block does not help to "distinguish the Act block from the rest of the test."

Expected behaviour

• Docs extended to show this scenario.

• Two possible options are described for resolution:

  1. change the hash-comment line into a full docstring:

  def test() -> None:
      """
      NOTE: the most interesting thing about this test is this comment
      """
      result = 1 + 1
  
      assert result == 2
  

  2. Inject a whitespace after the hash-comment line and before the act block:

  def test() -> None:
      # NOTE: the most interesting thing about this test is this comment
  
      result = 1 + 1
  
      assert result == 2
  

  Both of these solutions seem reasonable. Plus it creates a possibility of keeping the hash-comment - this might be a valuable option if hash comments are parsed by other tools, etc. For example my editor will highlight NOTE: in a hash comment, but not in a docstring.