neue Asuro Lib V2.70 (Release Candidate 3)

[Sternthaler]

schon den ein oder anderen Neuling überfordert.

Mhhmm, ich weiss nicht so recht. m.a.r.v.i.n hat die Datei install.txt angefangen und das ist ja schon ein funktionsfähiger Anfang.
OK, da kann man bestimmt noch dran arbeiten.
Wenn man aber davon ausgeht, dass bis jetzt ja noch nicht allzu viele Leute an der Lib mitgearbeitet haben und somit für die 'Endanwender' der Lib eigendlich nur noch das Kopieren an die richtige Stelle übrig bleibt, denke ich, dass doch auch Anfänger damit zurecht kommen werden.

Nun aber zu meinem ersten Muster aus der zerlegten m.a.r.v.i.n-Lib.
Als Anmerkung vorab:
Ich bin der Haarspalter und habe den angehängten Source nicht nur kommentiert (ganz bestimmt nicht im Sinne von Doxygen; den Hint von stochri habe ich jetzt gerade erst gelesen), sondern auch etwas umformatiert.
- Als erstes habe ich die TAB-Zeichen in BLANKS getauscht, so dass jeder beliebiege Editor einen einheitlich formatierten Text sehen kann.
- Dann habe ich vor die öffneden Klammern ( und [ immer ein Leerzeichen gesetzt.
- Alle Variablen und Funktionen habe ich 'besonders' eingerückt. Dazu folgendes Muster, warum ich das so gemacht habe:

volatile unsigned char  count36kHz;
static   unsigned char  global_daten1;
         unsigned long  global_daten2;
                  char  global_daten3 [100];


                  void  funktion (
         unsigned int  *data)
{
static   unsigned char  lokal_daten1;
         unsigned long  lokal_daten2;
                  char  lokal_daten3 [100];
}


static            int  *andere_funktion (
         unsigned int  *data,
                  char  steuerung)
{
static   unsigned char  lokal_daten1;
         unsigned long  lokal_daten2;
                  char  lokal_daten3 [100];
}

Und nun erst einmal die Datei adc.c als erster Versuch einer Kommentierung.

[m.a.r.v.i.n]

Hi,

Hilfe ist immer sehr willkommen. Gerade die Dokumentation ist derzeit sicher noch etwas dürftig. Dank einem Tool wie Doxygen läßt sich das aber hervoragend automatisieren und da die Dokumentation im Sourcecode mit drinsteht ist sie auch immer aktuell.

Was die Code Formatierung angeht, würde ich das lieber ebenfalls einem Tool überlassen. Dies wurde bisher absichtlich nicht gemacht. Das hat mit dem Versionsverwaltungssystem zu tun. Da beim änderen der Tabs in Spaces quasi jede Zeile geändert wird, würde auch die Versionsverwaltung jede Zeile als geändert betrachten. Man könnte nicht mehr unterscheiden, was jetzt wirkliche Codeändeungen waren.
Da mit der aufgesplitteten Lib sowieso alles neu wird, wäre jetzt der richtige Zeitpunkt, den Quellcode umzuformen. Ein entsprechendes Tool wäre z.B. Artistic Style. Damit lassen sich Quellfiles im nu umformatieren. Nicht nur Tabs und Spaces. Auch Einrückungen und Klammern kann man nach Belieben formatieren.

Als Coding-Styles würde ich vorschlagen:
* Ansi C Style für Klammern und Einrückungen
* Tabs mit 4 Spaces ersetzen.
* Funktionen und Variablen Namen und Definitionen in Englisch
* Kommentare in Deutsch

@sternthaler: bis auf die besonderen Einrückungen eine gute Idee. Ich glaube so etwas unterstützen die Quellcode Formatierer wohl nicht. Werde ich mir aber nochmal näher anschauen.

Die doxygen Kommentare sind auch in der neuen Lib noch vollständig drin. Ich habe nur aus Platzgründen die Examples weggelassen.

[Sternthaler]

Hab mal doxygen gezogen und etwas damit rumgespielt.
Hätte mich gewundert, wenn ich in der kurzen Zeit etwas Vernünftiges hinbekommen hätte.

Was ich bisher verstanden habe:
Alle dokumentierenden Stellen der Lib sind wohl nur in der asuro.h.

Ich frage mich ob dies sinnvoll ist.
Ich für meinen Teil schaue mir gerne den Code an, um die Funktionalität zu verstehen. (Liegt wohl daran, dass bei uns in der Firma die Doku nicht unbedingt verläßlich ist. Psst, nicht weitersagen!) Somit habe ich den Hang dazu, möglichst viel Doku im Source unterzubringen. Somit wäre dies aus meiner Sicht die richtige Stelle.
Andererseits ist es natürlich nicht verkehrt nur eine Stelle für den Doku-Text zu haben.
Als Vorteil für eine Dokumentierung in den C-Sourcen sehe ich allerdings, dass einzelne Sourcen OHNE Änderung der asuro.h gemacht werden können. Somit können sich noch mehr Leute beteiligen; ihre Duku an der Sourcestelle hinterlegen, und man muss nicht darauf aufpassen, dass die asuro.h von mehreren Leuten 'zerlegt' wird.
Z.B.: könnte jemand eine neue Funktion, in eigenem C-Source, für die Lib erzeugen, seinen Kommentar dort hinterlegen und nach der Integration in der Lib ist das erledigt.

Wie wollen wir vorgehen?

Wer fühlt sich im Moment eigendlich als Master-of-Asuro-Lib und pflegt/verwaltet neue Stände? (m.a.r.v.i.n bitte die Hand hoch)

@m.a.r.v.i.n
Auf eine 'besondere' Formatierung kann ich in der Lib auf alle Fälle verzichten.
Mit den 4 Blanks zum Einrücken habe ich leichte Probleme, da es mir häufig am Ende der Zeile zu knapp für einen //-Komentar wird. (Ich sehe zu, dass meine Sourcen nie breiter als 80 Char werden (alter Tunix-VI-User).)

Zu den Funktionen habe ich noch eine Anmerkung:
Englisch ist OK, aber mittlerweile habe wir Funktionsnamen mit und ohne _-Zeichen im Namen. Klar, mit Doku findet man das schnell herraus, aber sollten wir da nicht auch einheitlich werden? Wie, ist mir eigendlich egal, aber ich würde die ursprüngliche Schreibweise ohne _ bevorzugen, da ich recht sicher bin, dass der von Arexx mitgelieferte Source keine _'e benutzt und somit nicht jeder seine Sourcen umschreiben müsste.

So, erst mal (fast) genug.
Von Source-Formatieren halte ich nicht allzu viel. In der Firma haben wir ca. 30 Individualisten zum Code erzeugen; ich muss auf den Output acht geben, und hab noch keinen Formatierer gefunden der 30 Leute unter einen Hut gebracht hat. Ich bin da aber Vorurteilsfrei, solange es nicht zu stark aus irgendeinem Ruder läuft.

[m.a.r.v.i.n]

Hi,

Alle dokumentierenden Stellen der Lib sind wohl nur in der asuro.h.
Ich frage mich ob dies sinnvoll ist.

Die asuro.h ist nun mal die Schnittstelle des Anwenders zur Lib. Es spricht natürlich nicht dagegen die Funktionen in den c-Files ebenfalls mit Doxygen zu kommentieren. Ich hatte bisher nur keine Zeit dafür. Doxygen macht aber auch jetzt schon aus den c-Files ordentliche HTML Seiten.

Wie wollen wir vorgehen?

Der gesamte Quellcode befindet sich im CVS auf dem Sourceforge Server. Wer mitarbeiten willl, meldet sich am einfachsten als Entwickler bei Sourceforge an. Eine kurze email oder PN an mich mit dem Entwicklernamen und er bekommt Schreibrechte.
Sehr viel mühsamer wäre es, die Änderungen per email zu verschicken, oder hier im Forum zu posten. Komplette Zip-Files dagegen lassen sich leichter einhäkeln.

Statt CVS wäre es vielleicht besser, gleich auf SVN umschwenken.

Wer fühlt sich im Moment eigendlich als Master-of-Asuro-Lib und pflegt/verwaltet neue Stände?

da heb ich mal spontan die Hand.

Mit den 4 Blanks zum Einrücken habe ich leichte Probleme

OK, 2 Blanks sollten auch reichen.

Funktionsnamen mit und ohne _-Zeichen im Namen.

Da stimme ich dir zu. Die Unterstriche fliegen also raus.

Von Source-Formatieren halte ich nicht allzu viel.

Ich habe mal probehalber Artistic Style über die Lib gejagt. Sieht alles ganz sauber aus. Einrückungen sind damit problemlos änderbar.

RN-User madman2k hat einige der Sachen die hier gesagt wurden, bereits in der Asuro Lib 3.0 bei gna.org umgesetzt. Leider ist diese Lib hier im Forum nicht gut angekommen. Zum einen wurden von ihm alle Kommentare ins englische übersetzt und einige Funktionen umbenamst.
Es wäre schade, wenn es zwei Libs gäbe, die sich in unterschiedliche Richtungen entwickelt. Vielleicht gelingt es, die Lib 2-sprachig zu kommentieren (deutsch, englisch). Mich erreichen zur Lib doch des öfteren Mails aus dem Ausland, die mit der deutschen Doku nichts anfangen können. Allerdings scheint doxygen mit so etwas überfordert zu sein.

[stochri]

Hätte mich gewundert, wenn ich in der kurzen Zeit etwas Vernünftiges hinbekommen hätte.
Was ich bisher verstanden habe:
Alle dokumentierenden Stellen der Lib sind wohl nur in der asuro.h.

Hallo Sternthaler,
vor kurzem habe ich Doxgen mal ausprobiert und fand es eigentlich nicht schlecht. Ich habe einfach meine Funktionsköpfe mit dem entsprechenden Syntax /// oder

/*!
* Diese Funktion macht ... blabla
*/

in den *.c Files versehen und Doxygen drüberlaufen lassen. Das Ergebnis war eine recht schöne Dokumentation. Ich finde es übrigens auch besser, die Kommentare in die *.c files anstatt getrennt in die Header-Datei zu schieben. Ist ja schließlich beim Sourcecode durchlesen wichtig.

RN-User madman2k hat einige der Sachen die hier gesagt wurden, bereits in der Asuro Lib 3.0 bei gna.org umgesetzt. Leider ist diese Lib hier im Forum nicht gut angekommen. Zum einen wurden von ihm alle Kommentare ins englische übersetzt und einige Funktionen umbenamst.

Die Lib 3.0 stört mich ziemlich. Ich finde es eine Unverschämtheit, dass madman2k einfach die Nicknames aus den Funktionsköpfen entfernt hat und damit nicht mehr nachvollziehbar ist, wer an welcher Funktion gearbeitet hat. Meiner Meinung nach sollte man es in der Lib vorschreiben, dass die Autoren die an den Funktionen gearbeitet haben, in den Funktionsköpfen genannt werden.

Eine Funktion fehlt meiner Meinung nach übrigens noch: Einen Teilkreis fahren zu können z.B. in der Art

GoArc( int radius, int winkel );

int radius in mm
winkel in -360° ... +360°

Damit könnte man dem ASURO zu etwas runderen Bewegungen verhelfen.

Ich weiss nicht wann ich dazu komme, aber es könnte noch eine ganze Weile dauern.


Gruss,
stochri

[Sternthaler]

Die asuro.h ist nun mal die Schnittstelle ...

Ich bin, so wie stochri, doch auch eher für ein umlegen der Kommentare.
Die Arbeit kann ich übernehmen und die bestehende Doku ersteinmal platt umschreiben in den von dir getrennten Sourcen. Ich habe den von dir gepostenen ZIP-Stand.

Wer mitarbeiten willl, meldet sich am einfachsten als Entwickler bei Sourceforge an.

Werde ich heute Abend versuchen. Ich schicke dir dann gegen 2:30 eine Mail. Bitte um sofortige Antwort
Blöde ist nur, dass ich das zum ersten mal mache. Rechnet eher mit Fragen als einer gelungenen Anmeldung.

... gleich auf SVN umschwenken.

Da bin ich dafür, da ich SVN so halbwegs kenne. (Hey, und ich bin nun nicht mehr Windoof 98-User auf dem ja kein SVN-Server läuft. Hab über Weihnachten doch mal das veralterte XP installiert. Vista kann warten.)

da heb ich mal spontan die Hand.

SUPER

OK, 2 Blanks sollten auch reichen.

Einverstanden

Die Unterstriche fliegen also raus.

Kann ich im Zuge der Kommentar-Umlegung gleich mitmachen.
Ich hoffe, dass stochri dann nicht auch auf mich schimpfen wird.

v.i.n"]Artistic Style

Ziehe ich mir dann wohl auch mal.

.. die Lib 2-sprachig zu kommentieren (deutsch, englisch).

Da werde ich mich auch mal dran versuchen.

und fand es eigentlich nicht schlecht.

Stimmt, ich war auch überrascht was man da so alles machen kann. Ich hatte nur noch nicht den rechten Überblick wo die doxygen-Kommentar in unserer Lib eigendlich herkamen, als ich die ersten Versuche machte und hab da etwas hinterhergesucht. Die Doku zu doxygen kann sich echt sehen lassen.

Wer weiß denn, wie man die, fast immer leeren, Unterverzeichnisse wegkonfiguriert, die unterhalb des Doku-Output-Verzeichnisses angelegt werden? (Zumindest bei mir)

Ich finde es eine Unverschämtheit ...

Da kann ich nur zustimmen.
Inkompatibler Code und geänderte Funktionsnamen sind das eine, aber die Info, wer sich da so viel Mühe gegeben hat zu vernichten ist tatsächlich nicht so nett.


So, bevor ich nun aber anfange, da etwas 'in Echt' zu machen, werde ich folgendermassen vorgehen.
1. Anmelden bei Sourceforget.
2. Mail an m.a.r.v.i.n
3. 'Artistic Style' testen (der Einwand, dass dann jede Zeile als geändert moniert wird, ist dann ja nur einmal vorhanden.
4. Hier im Thread auf weitere Einwände / Ideen / Vorschläge WARTEN
5. Startschuss zur Änderung sollten wir hier noch abstimmen.


Mir fällt noch folgendes ein:
Wenn man über die Forenauswahl geht, hat Frank immer einen Thread a la "Globale Ankündigung:" oder "Ankündigungen: Wie sieht der Asuro aus" in die niemand etwas reinposten kann. Der steht auch noch immer schön oben in der Liste.
Sollten wir Frank nicht mal darauf ansprechen, evl. so einen Thread zu bekommen, in dem Links zu den 'irgendwo' gespeicherten Libs (alle Versionen?) zum Asuro zu finden sind.
Dann müssten wir nur 'irgendwie' doch Zugang zu dem Eintrag bekommen, wenn es denn mal eine neue Lib gibt.

[m.a.r.v.i.n]

Hi,

die Asuro Lib ist nochmals überarbeitet worden und befindet sich jetzt als Release Candidate 1 im 1. Post dieses Threads als Attachment. Die wichtigsten Änderungen sind bereits eingeflossen (Siehe 1. Posting). Dieser Stand wird dann auch demnächst im SVN auf Sourceforge eingecheckt. (Hab leider noch etwas Probleme mit meinem SVN Client, um über SSH auf Sourceforge zugreifen zu können).

@sternthaler. Leere Verzeichnisse bei der Doku Erstellung bekomme ich nicht.
Ich hab auch das doxyfile soweit geändert, das jetzt alle Pfadangaben relativ sind und dazu gibt es ein Batchfile zum Erstellen der HTML-Doku. Damit müßte es ohne Anpassung überall laufen.

[HermannSW]

Hi,

ich bin ein begeisterter Verwender der neuen Lib.

Hi,

die Asuro Lib ist nochmals überarbeitet worden und befindet sich jetzt als Release Candidate 1 im 1. Post dieses Threads als Attachment. Die wichtigsten Änderungen sind bereits eingeflossen (Siehe 1. Posting). Dieser Stand wird dann auch demnächst im SVN auf Sourceforge eingecheckt. (Hab leider noch etwas Probleme mit meinem SVN Client, um über SSH auf Sourceforge zugreifen zu können).
...

Hier gibt es eine Bereichsüberschreitung für z.B. PrintInt(-12345) (abschließendes '\0'), sollte vor Distribution auf char text[7] geändert werden:

void PrintInt(int wert)
{
  char text[6];
  itoa(wert,text,10);
  SerPrint(text);
}

Ich verwende häufiger GetTime(), und da kommt ein long zurück.
Verwendung von sprintf() und SerPrint() kostet wegen sprintf() viel codesize.
Wie wäre es mit PrintLong() in der Lib? (ich bin mittels PrintLong() ganz von der Verwendung von sprintf() abgekommen ...)

void PrintLong(long wert)
{
  char text[12]; // '-'1234567891'\0'
  itol(wert,text,10);
  SerPrint(text);
}

[m.a.r.v.i.n]

Hallo Hermann,

danke für die Infos. Das wird noch in die neue Release einfließen.

Den aktuellen Stand der Dinge kann man sich online betrachten und downloaden im SVN Repository unter
http://asuro.svn.sourceforge.net/viewvc/asuro/trunk/

Falls noch wer Ideen und Anemrkungen hat immer her damit. Auch aktive Mitarbeiter, die sich bei Sourceforge anmelden, sind auch immer willkommen.

[HermannSW]

Hallo,

...
Falls noch wer Ideen und Anemrkungen hat immer her damit.
...

mein Sohn und ich verwenden noch den Compiler von der Original-CD.

Die Idee, mittels #ifndef SIGNAL die verschiedenen Compiler-Versionen auseinanderzuhalten ist gut, und das #include <avr/signal.h> notwendig, aber leider nicht hinreichend.

Wir haben die neue Lib heute erstmals auf einen Rechner gespielt, und getan, was in install.txt stand. Ein anschließendes compilieren des IRCollisionTest lieferte:

...
avr-gcc -c -mmcu=atmega8 -I. -g -Os -I../../lib/inc -funsigned-char -funsigned-bitfields -fpack-struct -fshort-enums -Wall -Wstrict-prototypes -Wa,-ahlms=test.lst test.c -o test.o
In file included from test.c:13:
../../lib/inc/asuro.h:291: error: parse error before "leftpwm"
../../lib/inc/asuro.h:291: warning: function declaration isn't a prototype
../../lib/inc/asuro.h:300: error: parse error before "freq"
../../lib/inc/asuro.h:300: warning: function declaration isn't a prototype
make: *** [test.o] Error 1

Z.B. ist der Typ int8_t nicht definiert.

Könnte die neue Lib vor Release so o.Ä. angepaßt werden? (bei uns hat das die Probleme beseitigt)

...
#ifndef SIGNAL
  #include <avr/signal.h>   // header file obsolete in actual avr-libc
  #include <inttypes.h>
#endif
...