Hinweise + Vorschläge f. bessere Befehls-Beschreibungen etc.

Hier werden, insbesondere in den Beta-Phasen, Bugmeldungen gepostet. Das offizielle BugForum ist allerdings hier.
Kaeru Gaman
Beiträge: 17389
Registriert: 10.11.2004 03:22

Hinweise + Vorschläge f. bessere Befehls-Beschreibungen etc.

Beitrag von Kaeru Gaman »

Andre hat geschrieben:Daher würde es mich auch freuen, wenn die Mods diese beiden Threads nach Erscheinen der PB 4.20 final schließen würden. Und gleichzeitig können dann von den Mods neue eröffnet werden - am liebsten wäre mir ein Dreiteilung in folgende Themen:
1.) Schreibfehler & andere offensichtliche Fehler in der PB-Hilfe
2.) Hinweise & Vorschläge für bessere Befehls-Beschreibungen etc.
3.) Diskussionen & anderes rund um die PB-Hilfe.
Hier ist Thread No. 2
Der Narr denkt er sei ein weiser Mann.
Der Weise weiß, dass er ein Narr ist.
Little John

Beitrag von Little John »

In der deutschen Hilfe von PB 4.20 (Windows) zu Random() heißt es:
Beschreibung
Ergibt eine Zufallszahl zwischen 0 und dem angegebenen Maximal-Wert (einschließlich 0 und 'Maximum').
Das ist richtig aber ungenau. Random liefert nie Werte wie z.B. 2.7 oder 3.5.

Eine bessere Beschreibung ist daher:
"Liefert eine ganze Zufallszahl zwischen 0 und dem angegebenen Maximum (jeweils einschließlich)."

Gruß, Little John
Kaeru Gaman
Beiträge: 17389
Registriert: 10.11.2004 03:22

Beitrag von Kaeru Gaman »

ist da immer noch nix getan worden?

...außerdem fehlt der Hinweis, dass "Maximum" eine positive Long sein muss,
also Maximal $7FFFFFFF = 2147483647
Der Narr denkt er sei ein weiser Mann.
Der Weise weiß, dass er ein Narr ist.
Little John

Beitrag von Little John »

Zu meiner Überraschung funktioniert mit PB 4.20 folgender Code

Code: Alles auswählen

Define x.f

For x = 1 To 3 Step 0.1
   Debug x
Next
nicht, sondern verursacht die Fehlermeldung
An integer assignment is expected after 'For'
Hinter 'For' kann also offenbar nur eine Integer-Variable stehen. Logischerweise ergibt dann hinter 'Step' auch nur eine Integer-Konstante einen Sinn*.
Das ist sehr ungewöhnlich, denn in jeder anderen Hochsprache die ich kenne, können an diesen Stellen auch Fließkommazahlen benutzt werden. Um so wichtiger ist es, dass dies auch in der Hilfe dokumentiert wird.

Gruß, Little John
_____________________________

* PB akzeptiert an der Stelle auch eine Fließkomma-Konstante, was zu einer Endlosschleife führt -- aber das ist ein anderes Thema.
Little John

Beitrag von Little John »

Im Kapitel Int() (PB 4.20 Windows) heißt es:
Beschreibung
Gibt die Ganzzahl (Integer) einer Fließkommazahl zurück.
Die Ganzzahl einer Fließkommazahl gibt es nicht. Richtig ist z.B.:
"Gibt den Ganzzahl-Teil einer Fließkommazahl zurück."
oder
"Gibt den ganzzahligen Anteil einer Fließkommazahl zurück."

Entsprechdes gilt sinngemäß für IntQ().

Gruß, Little John
Kaeru Gaman
Beiträge: 17389
Registriert: 10.11.2004 03:22

Beitrag von Kaeru Gaman »

folgende Aussage von einem Boardkollegen hat mich stutzig gemacht:
In den Beispielen der Hilfe wird das ClearScreen auch immer direkt nach FlipBuffers gesetzt.
dann hab ich mal reingeschaut, und mir fiel auf, dass das Flip des öfteren ganz am Anfang der Schleife steht,
wo noch garnix auf dem Backbuffer steht was hergeflippt werden könnte.

Der Kollege hat dann in einer Procedure zur Darstellung eines einzelnen
Frames in einem WindowedScreen das Clear ganz ans Ende geschrieben,
hinter das FlipBuffers.
völlig unerklärlicher Weise hat es im vorliegenden Falle zu einem Darstellungsfehler geführt.
ich bin dort nicht stärker eingestiegen, der Fehler war einfach verschwunden,
nachdem ich rein spaßeshalber mal das Clear an den Anfang gesetzt hatte.
(wenn jemand neugierig ist das zu ergründen, das Topic ist dieses hier.)

Warum ich jetzt hier schreibe...
könnte man vielleicht mal die Beispiele in der Help dahingehend überarbeiten,
dass die Befehle in einer semantisch logischen Reihenfolge stehen?

Klar, man kann darüber streiten, was Stil ist und was nicht und was wichtig ist und was nicht...

Aber rein basistechnisch löscht man einen Buffer, dann beschreibt man ihn, und dann stellt man ihn dar.
und ganz egal ob es in einer Schleife stattfindet und sowieso immer wiederholt wird,
es ist ganz einfach sinnvoll und hilft auch Anfängern ein Gefühl für die Vorgänge zu bekommen,
wenn die Beispiele in dieser Hinsicht "richtig" wären.
Der Narr denkt er sei ein weiser Mann.
Der Weise weiß, dass er ein Narr ist.
marco2007
Beiträge: 906
Registriert: 26.10.2006 13:19
Kontaktdaten:

Beitrag von marco2007 »

z.B.:

Code: Alles auswählen

StructureUnion
Sie funktionieren wie das 'Union' Schlüsselwort in C/C++
...Hinweise/Vergleiche sind gut, aber Beispiele wären manchmal besser:
http://www.purebasic.fr/german/viewtopi ... ctureunion
Windows 11 - PB 6.03 x64
_________________________________
Little John

Beitrag von Little John »

Aus der Beschreibung von CatchImage() (PB 4.20):
Dies kann einem Absturz vorbeugen, wenn der Umgang mit Bildern von einer unbekannten Position versucht wird, welche beschädigt sein können.
Ich bin mir nicht sicher, wie der Satz zu verstehen ist. Evtl. ist folgendes gemeint:
Dies kann einem Absturz vorbeugen, wenn versucht wird Bilder unbekannter Herkunft zu laden, welche beschädigt sein können.

Gruß, Little John
Kaeru Gaman
Beiträge: 17389
Registriert: 10.11.2004 03:22

Beitrag von Kaeru Gaman »

oh ja, der satz ist wirklich kritisch. das original lautet
It can prevent a crash when trying to handle images from an unknown location, which can be corrupted.
der sinn dahinter dürfte sein:
wenn man als parameter eine Variable angibt, und sich an der Stelle gar kein bild befindet,
könnte der Algorithmus sich "totlesen", falls keine Maximalgröße angegeben wird.

auf der Seite ist noch etwas unschön:
zum Beispiel wenn der Desktop in 16 Bit ist und das Bild in 24 Bit.
ein Desktop ist nicht in Bit, und ein Bild auch nicht.
(jedenfalls hoffe ich, dass in meinem Bit kein Desktop ist *in die Flasche lunz*)
die Desktopauflösung ist auf 16 bzw. 32bit (Farbtiefe) eingestellt.
=>
"zum Beispiel wenn versucht wird, ein Bild mit 24Bit Farbtiefe auf einem Desktop mit 16bit Farbtiefe zu laden."
Der Narr denkt er sei ein weiser Mann.
Der Weise weiß, dass er ein Narr ist.
Little John

Beitrag von Little John »

PB 4.20-Hilfe zu ReadData() hat geschrieben:Liest den Inhalt der '#Datei' in den angegebenen Speicherbereich '*Speicherpuffer'. 'ZuLesendeLaenge' gibt die Anzahl der einzulesenden Zeichen an.

'Laenge' enthält nach der Ausführung des Befehls die Anzahl der tatsächlich eingelesenen Zeichen.
Ich denke nicht, dass es hier um Zeichen geht, zumal ein Zeichen 1 oder (bei Unicode) 2 Byte groß sein kann (das wäre doch sehr umständlich). Ich meine, in obigem Text muss es nicht Zeichen, sondern Byte heißen.
PB 4.20-Hilfe zu ReadData() hat geschrieben:'Laenge' enthält nach der Ausführung des Befehls die Anzahl der tatsächlich eingelesenen Zeichen. Dies ist nützlich für Überprüfungszwecke.
Und zwar ...? Wo soll das sinnvollerweise wie überprüft werden? Auf Grund von längerer Programmiererfahrung hatte ich eine Vermutung (die offenbar auch zutrifft), aber das muss natürlich auch dokumentiert werden, denn v.a. Programmieranfänger können allein mit dieser Aussage wenig anfangen.
PB 4.20-Hilfe zu ReadData() hat geschrieben:Für ein Code-Beispiel sehen Sie zum Lof() Befehl.
Das Beispiel ist ja gut zur Demonstration des Lof()-Befehls, aber ein allgemeingültiges gutes Beispiel für ReadData() ist das nicht. Hier ist ein besseres Beispiel für ReadData(), das auch verdeutlicht wie die oben angesprochene Überprüfung realisiert wird:

Code: Alles auswählen

; Dies ist nur zur Demonstration, es gibt einen PureBasic-Befehl CopyFile().

EnableExplicit

#MaxChunk = 4096

Procedure.l Copy (infile.s, outfile.s)
   Protected buffer.s
   Protected ifn.l, ofn.l, bytes.l

   ifn = ReadFile(#PB_Any, infile)
   If ifn = 0
      ProcedureReturn #False          ; error
   EndIf

   ofn = CreateFile(#PB_Any, outfile)
   If ofn = 0
      CloseFile(ifn)
      ProcedureReturn #False          ; error
   EndIf

   buffer = Space(#MaxChunk)
   Repeat
      bytes = ReadData(ifn, @buffer, #MaxChunk)
      WriteData(ofn, @buffer, bytes)
   Until bytes < #MaxChunk
   CloseFile(ofn)
   CloseFile(ifn)
   ProcedureReturn #True              ; success
EndProcedure

Define infile.s, outfile.s

infile = "source.dat"
outfile = "target.dat"
If Copy(infile, outfile)
   Debug "OK"
Else
   Debug "Fehler"
EndIf
Gruß, Little John

PS: Wörter wie "einlesen", "ausdrucken" etc. sind stilistisch sehr unschön. Besser ist schlicht "lesen", "drucken", ...
Antworten