Review main Merged

72500[DOCS] Improve PHPDoc comments of RedirectWasHitEvent

Lina Wolf CR +2 V +2 Easy +5 −2 updated 12/04/21, 19:19

Commit message

Review

  • Code review CR +2 Done
    • Andreas Kienast +2
    • Christian Kuhn +1
  • Verified V +2 Done
    • Andreas Kienast +2
    • Christian Kuhn +1
    • core-ci +1 CI

Issues 1

Files 1

Review log 1317

  1. Lina Wolf uploaded patch set 1 12/04/21, 09:45

  2. core-ci voted on patch set 1 V +1 12/04/21, 10:03 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/20547

  3. Christian Kuhn commented on patch set 1 CR -1 12/04/21, 12:50

    RedirectWasHitEvent.php:52

    That's pretty much useless: The return type hint already states a PSR-7 ServerRequestInterface is returned. We lately tend to actively remove those comments when the method signature says everything already. Let's not add it again.

    RedirectWasHitEvent.php:60

    same

    RedirectWasHitEvent.php:88

    same

    RedirectWasHitEvent.php:96

    same
  4. Lina Wolf commented on patch set 1 12/04/21, 13:34

    RedirectWasHitEvent.php:52 Reply

    However the type hint only states what type is returned here. The method name also just says a quite genereric "getRequest". I think "This method returns the current PSR-7 Request" is additional information? This also enables us to generate the API part of the documentation, see here: https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi/pull/1629/files#diff-0a8c33c137beb3bf67a608239748e49bbead89b2cee90a8ae3965d48b3ce2fbd
  5. Lina Wolf uploaded patch set 2 12/04/21, 13:51

  6. Lina Wolf commented on patch set 2 12/04/21, 13:52

    RedirectWasHitEvent.php:88 Reply

    Done
  7. core-ci voted on patch set 2 V -1 12/04/21, 13:53 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/20561

  8. Lina Wolf uploaded patch set 3 12/04/21, 13:55

  9. Christian Kuhn commented on patch set 3 12/04/21, 14:04

    RedirectWasHitEvent.php:52 Reply

    Mmmh. I'd say it's obvious the "current" request is returned - simply because there is no other one. This is an event fired when a redirect is edited in the backend, so yeah, it is of course the current backend request. API docs: The methods says on a language level that a ServerRequestInterface is returned. There is simply not much to add. We're only talking about events here regarding the API docs question? If so, I don't really insist on not adding this doc header comment ... because well, even if it does not add any information, it also does not hurt - it basically just makes the class longer and less compact to read. For other cases in "normal" core code (not events), I personally tend to not accept such a header anymore - having a series of fully types properties directly below each other with only a single line and having methods without comment since those wouldn't add information due to fully typed properties (example: trivial getters, injected dependencies, ...) is just much more dense and easier to grasp. I like that very much. For events ... well, if you really want it and think it helps docs ... I don't care that too much. How do you decide?
  10. core-ci voted on patch set 3 V +1 12/04/21, 14:07 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/20562

  11. Andreas Kienast commented on patch set 3 12/04/21, 15:34

    RedirectWasHitEvent.php:52 Reply

    I agree with lolli here that documenting getters, whose names already imply what is returned, is superfluous. With recent changes, there are PSR-7 requests/responses only so it mustn't get documented explicitly that it's PSR-7.
  12. Lina Wolf uploaded patch set 4 12/04/21, 19:02

  13. Lina Wolf commented on patch set 4 12/04/21, 19:04

    RedirectWasHitEvent.php:52 Reply

    Done

    RedirectWasHitEvent.php:60 Reply

    Done

    RedirectWasHitEvent.php:96 Reply

    Done
  14. Christian Kuhn voted on patch set 4 V +1 CR +1 12/04/21, 19:08

  15. core-ci voted on patch set 4 V +1 12/04/21, 19:17 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/20576

  16. Andreas Kienast voted on patch set 4 V +2 CR +2 12/04/21, 19:19

  17. Andreas Kienast merged patch set 5 12/04/21, 19:19