Clarify undefined behavior when target == source in PMatrix::mult docs

Offen Anfängerfreundlich
  • Stimmt etwas nicht?
#1,591 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
1/5
Geschätzter Aufwand
Unter einer Stunde
Anfängerfreundlichkeit
85/100
Issue-Typ
Dokumentation
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
java
Bereich
documentation

Rechercherichtung

Lies den Javadoc zu PMatrix.mult in core/src/processing/core/PMatrix.java, etwa in den Zeilen 165–171. Stelle klar, was passiert, wenn target und source dasselbe Objekt sind, und korrigiere die Formulierung, die den Rückgabewert als Matrix bezeichnet. Fertig ist die Änderung, wenn die Dokumentation das Verhalten korrekt beschreibt und den Rückgabewert als PVector bezeichnet.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Hi folks!

I know this won't be top priority, but this issue caused me to spin my wheels for a couple days straight since it was one of those times where all my logic "looked right" after many passes so I figured it might throw some other beginners for a loop.

I'd like to request additional clarity be added to the javadoc here:

https://github.com/processing/processing4/blob/cd50e02e5a8cdf41f8bb165b6ebd85feeeeac543/core/src/processing/core/PMatrix.java#L165-L171

Specifically, I think that it should be stated explicitly that behavior is undefined when target == source. Since no warning was offered I did not expect for the contents of source to still be in the process of being read by the time that target is actually being populated within this method but it appears something like that is happening (my expectation was that the contents of source would have probably been extracted into local variables once at the beginning since there are so few elements in a PVector and then loaded into target once at the end after performing intermediate computations). Ideally, if there is no utility in allowing target == source whatsoever, this case should throw an exception but, alternatively, additional doc clarity would have been a noninvasive way of preventing prolonged confusion in my case. Also I think "target will then be the matrix returned" is a typo since this method is returning a PVector.

Here is an example sketch you can use to observe the undocumented undefined behavior. Move the mouse around without pressing anything to observe normal behavior when simply passing target = null. Similarly, pressing Right-click will set target equal to a PVector reference which is fixed across draw() frames--the outcome of which is normal behavior. Pressing Left-click will pass target = source triggering the undefined behavior.

Thanks!

Vorherrschende Sprache
Java
Sterne
527
Forks
190
Ø Merge
1 T. 4 Std.
Gemergte PRs (30 T.)
3

Entwicklungsumgebung

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus processing/processing4

Alle Issues in processing/processing4

Ähnliche Issues

Weitere Issues zu Java

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.