Wie findet ihr die Doku/Beschreibung?

Maxi

Hiho!

Für ein Projekt wo ich jetzt schon ganz schön lang dran sitze, schreib ich grad an der Dokumentation für die Analyse-Plugins.
Darum gehts: Es ist ein Programm, welches kurz gesagt, aus Bildern von Tieren Muster der Tiere extrahiert und diese dann miteinander vergleicht. Mit den Plugins können noch extra Informationen wie Fundort usw. hinzugefügt werden.

Wie findet ihr diese Seite?

Ist es verständlich, wenn man kaum weiß, worums geht?
Ist die Grammatik sehr schlecht?
Was könnte man verbessern?

Grüße, Maxi

Hallo

Die Links oben in der Ecke sind tot.

chrische

hustbaer

Da du fragst... sind schon einige Sachen die ich kritisieren könnte

analyze -> analysieren
analysis -> analyse

Es sollte also IMO "analysis plugin" und nicht "analyze plugin" heissen. Schätze ich mal.

Die Grammatik ist stellenweise auch etwas daneben. Und nachdem ich das alles gelesen habe hab' ich nu kaum eine Ahnung was das alles soll. Aber egal, vielleicht versteht man das wenn man die restliche Doku zu dem Programm hat. (Wie z.B. auch die Doku zu Klassen wie cStomachPattern, cImage oder cDBConnector fehlt.)

cDBConnector sollte vielleicht auch cDBConnection heissen, oder ist cDBConnector eine "Connection-Factory"?

Und es ist z.T. etwas schwerfällig zu lesen.

Ein Beispiel:

Pattern  This parameter contains a reference to the newly created stomach
         pattern. You can modify this with the methods from the interface,
         it would mainly be adding or deleting properties. 

StomImg  This parameter contains a const reference to the image portion from
         which the pattern was exactly created. Mostly it should be a coloured
         alternative to the abstracted stomach pattern object. You are not
         allowed to modify the image, that's why it is a const reference. 

OrigFileName  This parameter contains the name of the image file that was loaded to create the pattern.

-->

Pattern  the stomach pattern to extend and/or modify.

StomImg  the image portion from which the pattern was created. More often
         than not this will be a coloured variation of the abstracted stomach
         pattern object (*).

OrigFileName  the name of the image file used to create the pattern.

Erklärung: "This parameter contains a const reference to" ist überflüssig, da das "const cImage&" es schon dokumentiert - es nervt nur wenn man "drüberlesen" muss. Genauso der letzte Satz den ich ersatzlos gestrichen habe ist wahrscheinlich überflüssig, da wiederum das "const" es bereits dokumentiert. Wenn die Klasse cImage "richtig" programmiert ist, ist es sowieso nicht möglich ohne "const_cast" da irgendwas dran zu verändern, und dass man das const nicht wegcasten darf muss man nicht dokumentieren -- sollte man einmal einen Fall haben wo es erlaubt wäre das "const" wegzucasten DANN gehört der dokumentiert (und auch warum das erlaubt ist), und auf jeden Fall sollte man sich überlegen ob man es nicht schöner (ohne "const wegcasten" zu erlauben) lösen kann (oft hilft "mutable" aber da kommen wir zu weit vom Thema ab).

(*) Hier kann ich nur raten. Was ist ein "abstracted stomach pattern object" wie kann ein Bild (cImage) eine "coloured alternative" von einem "pattern object" sein??? Hm. Und was soll "alternative" bedeuten?

2 grundlegende Dinge:

* weniger das erklären was jedem Programmierer der die entsprechende Sprache beherrscht sowieso klar ist (const, Referenzen, Pointer, ...), sondern eher kurz halten um den Leser nicht zu "ermüden".
* nicht gleich vorweg erklären wozu etwas gut ist, sondern erstmal was es ist bzw. macht, und zwar so präzise wie möglich. Wenn dann noch nicht klar ist wozu man es einsetzt bzw. warum man es braucht, DANN schreibt man eine Erklärung dazu.

Und Funktionen wie HasProperty, SetProperty oder GetProperty braucht man IMO garnicht zu erklären, hier tut es der prototype, maximal noch ein kurzer Satz (< eine Zeile) pro Funktion was sie tut (für ganz doofe quasi). Klassische "brief" Doku bei DoxyGen halt. Was allerdings erklärungsbedürftig ist (weil IMGO unsauberes Design) ist warum diese Funktionen direkt in cStomachPattern zu finden sind. (Ich würde davon ausgehen dass man ein "property collection" Interface hat, und cStomachPattern ein Member "GetProperties()" hat welches genau so ein Interface zurückliefert. Dann kann man das auch an mehreren Stellen verwenden wo Properties gebraucht werden.)

LordJaxom

hustbaer schrieb:

analyze -> analysieren

British: to analyse
American: to analyze

Nur mal so

hustbaer

Und? "analyze" stammt nicht von mir sondern vom OP, ich weise nur darauf hin dass das im Englischen nicht als Haupwort geht sondern nur als Verb.
Dass es im britischen Englisch garnicht geht ist dabei doch wohl ziemlich egal, oder?

Maxi

Hi!

Vielen dank, hustbaer, dass du dir das durchgelesen hast OK... vielleicht hab ichs mir auch zu einfach gedacht. Wahrscheinlich muss man ein bisschen mehr über den hintergrund wissen. Also ich habs jetzt nochmal überarbeitet, is gleicher Link. Hab jetzt auch Analyze in Analysis umbenannt

hustbaer schrieb:

Die Grammatik ist stellenweise auch etwas daneben.

Wo? kann nicht so gut englisch, also sag mal wo man was nicht versteht/wo sichs blöde anhört.

Die Klassen zu cImage, cStomachPattern und cDBCOnnector hab ich absichtlich weggelassen. cImage ist einfach ein Bild, das man zeichnen kann. cStomachPattern ist das Objekt, welches das eigentliche Muster darstellt. Kann es zeichnen und es mit anderen Mustern vergleichen. cDBConnector ist die Verbindung zu einer externen Datenbank, zB MSAccess. Benutzer können entscheiden, wie sie die externe datenbank anbinden wollen, der standardverbinder verbindet eben mit einer MSAccess-DB und schreibt da sachen rein, wie eben auch die extra -informationen die plugins den mustern geben.
Ob es auch cDBConnection heißen sollte... Also naja, es ist ja schon die Verbindung von Programm und Datenbank, andererseits ist für mich eine DBConnection wirklich nur die reine verbindung, über die man dann selber mit SQL usw. anfragen stellt. DBConnector ist für mich so eine art manager der das SQl selber erstellt und auch sonst viel selbständiger ist, deshalb heißt er DBConnector. Ist also ncih so zu sehen, dass er die verbindung erstellt (macht er auch), sondern eher als person, der die Verbindung herstellt und bearbeitet und überwacht.

Die Parameter und sonstige Beschreibungen hab ich jetzt überarbeitet und teilweise ganz schön gekürzt.

Ja, das das Image objekt const ist ist ganz klar deswegen, weil man da nichts verändern soll, also bilddaten. Das gehört nciht ins plugin. (Oder doch??? hm.. müsst ich mal überlegen )

hustbaer schrieb:

(*) Hier kann ich nur raten. Was ist ein "abstracted stomach pattern object" wie kann ein Bild (cImage) eine "coloured alternative" von einem "pattern object" sein??? Hm. Und was soll "alternative" bedeuten?

Das war so gemeint; Im programm werden aus fotos von bäuchen von salamandern deren Muster extrahiert. Die Muster sind dann in rot-schwarz binarisiert. Das cImage objekt stellt dann den Originalteil dar, also in bunt, und das cStomachPattern das rot-schwarze. deshalb hab ich geschrieben dass cImage da die farbige alternative zu dem abstrakten rot-schwarz muster ist. Der mensch kann auf sonem bunten bild mehr erkennen als auf dem rot-schwarzen.

hustbaer schrieb:

* nicht gleich vorweg erklären wozu etwas gut ist, sondern erstmal was es ist bzw. macht, und zwar so präzise wie möglich.

aber wenn ich schreibe was etwas macht, dann ist das doch wozu es gut ist, oder versteh ich dich da jetzt falsch? Hast du da jetzt ein konkretes Beispiel dafür in dem Text von mir?

Habe jetzt auch das Property interface vom Muster getrennt und sProperty in sVariant umbenannt. Nach Überlegen ist das wirklich besser so, ich brauch zwar zZ kein anderes objekt mit properties, aber so kann man das später auch viel einfacher benutzen.

Viele Grüße, Maxi