Notification-Doku...

  • Gibt es bitte irgendwo ein Tutorial zu der Notification-API?
    Es gibt den NotificationObjectType, das NotificationObject und das NotificationEvent..da blickt ja kein Mensch durch ohne Dokumentation. Vorallem dann wenn es einmal NotficationObject::getLink() und NotificationEvent::getURL() oder NotificationEvent::getTitle() und NotificationObject::getTitle() gibt. Woher soll ich ohne Doku wissen, was der Unterschied ist? Ich habe ehrlich gesagt keine Lust mich durch den ganzen WCF Quelltext zu lesen..
    Wäre echt mal hilfreich, wenn die Doku weiter ausgebaut wird!

  • Nein, es gibt kein Tutorial für die Benachrichtungsschnittstelle des Community Framework.


    Aber als Entwickler und Verkäufer von kommerziellen Produkten solltest du durchaus in der Lage sein, dir selbstständig die Interfaces zur Hand zu nehmen und dir die darin stehenden Kommentare anzusehen, oder? Wenn du dann noch Verständigungsschwierigkeiten haben solltest, kannst du dann immer noch explizit fragen. Eine komplette Erklärung jeder Kleinigkeit wirst du (vermutlich) hier nicht bekommen, aber das NotificationObject würde z.B. einen Beitrag wiederspiegeln. Ein NotificationEvent wäre z.B. die Benachrichtigung bei einer Zitierung deiner Person in einem Beitrag.


    Andere Entwickler haben übrigens ihre bisherigen Produkte auch ohne Dokumentation entwickelt und die Benachrichtungsschnittstelle erfolgreich implementieren können, indem sie sich die gebenenen Sachen (als Implementierungsreferenz steht seitens WoltLab z.B. das Burning Board zur Verfügung) angesehen haben.

  • Natürlich kann ich mit die Interfaces anschauen. Aber was bringt es wenn bei beiden Methoden "returns the title" dran steht?
    Und wieso bietet WoltLab dann überhaupt ein offenes Framework an wenn sie es nur halbherzig dokumentieren. Wenn man sich jede API anschauen müsste dauert das viel zu lange.

  • Wenn man sich jede API anschauen müsste dauert das viel zu lange.


    Kein Grund, da andere Entwickler dies auch gemacht haben. Und die Benachrichtigungsschnittstelle ist jetzt nicht sonderlich umfangreich, um sie als Alteingesessener nicht verstehen zu können, zumal es halt Referenzimplementationen in den WoltLab-Produkten gibt. ;)


    Deine Aussage "Aber was bringt es wenn bei beiden Methoden "returns the title" dran steht?" zeigt mir, dass du dir die entsprechenden Interfaces nicht einmal angesehen hast:
    NotificationObject implementiert wcf\data\ITitledObject . getTitle() sollte daher den Titel deines Objekts zurückliefern.
    Das Interface vom NotificationEvent ist mehr als verständlich dokumentiert: https://github.com/WoltLab/WCF…cationEvent.class.php#L21


    Richtig, es ist ein offenes Framework, welches frei verfügbar auf GitHub liegt. Als jemand, der sich schon länger mit den Produkten von WoltLab beschäftigt, solltest du das gewisse KnowHow haben, um dich an der Dokumentation beteiligen zu können. Ich habe mir jetzt gerade in drei Minuten auch nur eben die Klassen auf GitHub aufgerufen, um dir diese Antwort zu geben. Ein komplettes Durchforsten des Quelltextes von Community Framework ist, anders wie schreibst, nicht notwendig.

  • Mal ganz abgesehen davon das es doch mittlerweile genügend PlugIns gibt, die das nutzen.
    Die Beispiele liegen zuhauf?

    Browser: Opera (stable; up-to-date; ghostery; ublock)
    System: Windows 10


    Bald im Woltlab Store erhältlich: Luminary

    - Weitere Informationen unter dnw.thdn.de

  • Andere Entwickler haben übrigens ihre bisherigen Produkte auch ohne Dokumentation entwickelt


    Du machst es Dir zu einfach.
    Dieses Entwickeln ohne Dokumentation ist extrem ineffektiv. Wegen der sehr mäßigen Kommentierung des WCF fängt das mit viel Sucherei an, ohne genau zu wissen, wonach man suchen muss, und hört das mit zeitintensiven trial&error-Paketen auf. Und nicht selten erfährt man nach Stunden 'Arbeit' hier im Forum, dass die eine oder andere Sache überhaupt nicht normal funktionieren kann, sondern für irgendeinen Ajax-'Kram' ausgelegt ist (den man im Plugin nicht nutzen kann). Undokumentiert. Super.


    Und dieses Argument 'schau dir Beispiele an' zieht auch nicht, weil es für genug Sachen im WCF/WBB keine Beispiele gibt. Was ja irgendwie auch ein Grund dafür ist, ein Plugin zu schreiben. Aber selbst vorhandene Beispiele lassen sich nicht selten nur mühsam nutzen, weil es im WCF/WBB mal so und mal so umgesetzt ist - ohne erkennbare Gründe für die Unterschiede und ohne Hinweise der Entwickler.


    Mit einer vernünftigen Donkumentation und Standardisierung im WCF könnte man Plugins in einem Bruchteil der Zeit und wohl auch mit deutlich besserer Qualität (von Anfang an) schreiben können.


    Und aus Neugier: warum reitest Du eigentlich immer darauf rum, dass er kostenpflichtige Plugins entwickelt? Das stellt weder andere Anforderungen an die Entwicklung, noch macht es das Herumwühlen im WCF einfacher.

  • Sowohl @UdoZ als auch @Christopher Walz haben einen guten Punkt.


    Ich habe schon vor langer Zeit die Doku des WCF 2.0 kritisiert. Das Problem ist einfach, dass die PHPDoc oft Tautologien enthält und sehr nichtssagend ist. Der verlinkte Issue auf GitHub enthält Beispiele. vergleicht man dies z.B. mal mit der JavaDoc des JDK, dann liegen da Welten zwischen. Dort ist es nicht unüblich, dass genausoviel Text als Kommentar vorhanden ist, wie Quelltext.


    Das ganze ist einfach nervig und zeitraubend. viele ginge um ein dutzendfaches schneller, wenn eine vernünftige PHPDoc da wäre. Das fängt mit so einfachen Sachen an wie einer vernünftigen Beschreibung von Rückgabewrten oder zu übergebenden Parametern. Vgl. @return string Returns the type of the request und @return string Returns the request type. One of 'page', 'form' or 'action' oder @return string 'page' | 'form' | 'action'. Erstes ist der status quo. Da darf man erstmal den Quelltext durchsuchen, um rauszufinden, was da nun kommt ('Form' oder 'form'?) oder nen var_dump machen. bei letzterem ist einem sofort klar, was passiert. Und das ist nur eines von tausenden beispielen bei der Doku, die sich alle addieren und zu unnötigem Zeitaufwand führen (und ein sehr, sehr einfaches Beispiel, es gibt noch wesentlich schlimmere).


    Die Tutorials im Wiki sind ein guter Anfang, sind allerdings auch noch sehr unvollständig. Und sie können eine ausgiebige PHPDoc nicht ersetzen, nur begleiten!


    Am besten wäre sicherlich, wenn jeder Entwickler, der auf undokumentiertes Verhalten trifft, einen PR einreicht, der die Dokumentation ergänzt und am besten auch ein Tutorial schreibt. Damit wäre nämlich dann auch allen anderen geholfen (nunja, noch besser wäre gewesen, wenn WoltLab selber die Doku machen würden, aber das da viel passiert, halte ich für unrealistisch).

    "A life is like a garden. Perfect moments can be had, but not preserved, except in memory. LLAP" — Leonard Nimoy

  • Am besten wäre sicherlich, wenn jeder Entwickler, der auf undokumentiertes Verhalten trifft, einen PR einreicht, der die Dokumentation ergänzt und am besten auch ein Tutorial schreibt. Damit wäre nämlich dann auch allen anderen geholfen (nunja, noch besser wäre gewesen, wenn WoltLab selber die Doku machen würden, aber das da viel passiert, halte ich für unrealistisch).


    Obwohl man ja mit dieser Version Besserung gelobt hat... Eigene Pull-Requests würden schnell aus dem Ruder laufen, weil das ja sogut wie jede Methode und Variable betrifft. Für die eigene Tutorials ist das Wiki aktuell gesperrt.

  • Eigene Pull-Requests würden schnell aus dem Ruder laufen, weil das ja sogut wie jede Methode und Variable betrifft.


    Das heißt ja nicht, dass man es nicht wenigstens versuchen kann. Man kann die PRs ja auch klassenweise anfertigen.


    Quote

    Für die eigene Tutorials ist das Wiki aktuell gesperrt.


    Man kann solche Tutorials auch wo anders sammeln. Entweder hier im Forum, oder auf einer anderen Plattform. Ggf. einfach in einem eigenen GIT-Repo, dort könnte man sogar die GH-Pages branch nutzen. Evtl. setze ich solch ein Repo mit Jekyll sogar um, dann können interessierte dort einfach in einem von Jekyll unterstützen Markup ihre Tutorials veröffentlichen. Alleine kann ich so etwas jedoch nicht füllen. gegenlesen und PRs mergen sowie das Grundgerüst bauen kann ich aber durchaus. Wenn ich mich an den WCF Templates orientiere findet sich evtl. sogar ein Designer, der das ganze mit einem Design unterstützen will. Ansonsten wirds Bootstrap :P

    "A life is like a garden. Perfect moments can be had, but not preserved, except in memory. LLAP" — Leonard Nimoy

    • Official Post

    Ich bin momentan zu sehr mit der Entwicklung beschäftigt und habe nicht die Zeit gefunden, mich weiter mit der Dokumentation zu beschäftigen. Eine vernünftige Dokumentation ist nicht "auf die Schnelle" umsetzbar, für jeden einzelnen Artikel brauche ich Zeit und Ruhe, auch damit jeder Artikel allgemein verständlich formuliert wird, ohne das etwas unter den Tisch fällt.


    Sollte jemand ein ernsthaftes Interesse daran haben, mich bei der Ausarbeitung der Dokumentation zu unterstützen, so kann ich gerne den Schreibzugriff auf das Wiki freigeben. Leider erlaubt GitHub gegenwärtig keine Pull-Requests, daher kann ich entweder das Wiki für alle Beschreibbar machen oder ich muss einzelne Benutzer als Collaborator hinzufügen, dies geht allerdings mit Push-Berechtigungen für das WCF-Repository einher :/

  • Wenn ich mich an den WCF Templates orientiere findet sich evtl. sogar ein Designer, der das ganze mit einem Design unterstützen will.


    Klingt interessant, ich könnte mir vorstellen da auf seiten des Designs mitzuwirken.


    dies geht allerdings mit Push-Berechtigungen für das WCF-Repository einher


    Das ist dann natürlich eine ungünstige Situation für euch. Würdet ihr denn eine Community-Lösung wie von @Netzwerg vorgeschlagen unterstützen?

  • WoltLab arbeitet am WCF 2.1, und aus der Community ist bisher kaum etwas brauchbares entstanden. Es gibt ein paar Tutorials, aber die sind über mehrere Seiten verstreut. Eine gute, zentrale Anlaufstelle hat sich bisher nicht ergeben.

    "A life is like a garden. Perfect moments can be had, but not preserved, except in memory. LLAP" — Leonard Nimoy

    • Official Post

    Mit WCF 2.1 werden sich eh einige, größere Änderungen am Notification-System ergeben (die API bleibt aber zu 100% kompatibel); Die Dokumentation des Notification-Systems wird wahrscheinlich eh ziemlich umfangreich ausfallen, daher würde ich das Ganze lieber in "einem Rutsch" im Wiki verewigen.

  • Mit WCF 2.1 werden sich eh einige, größere Änderungen am Notification-System ergeben (die API bleibt aber zu 100% kompatibel); Die Dokumentation des Notification-Systems wird wahrscheinlich eh ziemlich umfangreich ausfallen, daher würde ich das Ganze lieber in "einem Rutsch" im Wiki verewigen.


    Und inwiefern wird sich hier was ändern? Kann man dazu schon etwas sagen

    Gruß Alex

  • Die Antwort ist gut.


    Sind ja nur noch ca 5 Monaten bis ende des Jahres.


    Dann nimmt man noch die betas, also kann es ja nicht allzu lange dauern ^^

    Gruß Alex