Lua documentation interface

[Willem Van Onsem]

• De documentatie van IDP ondersteund geen correct formaat bij het selecteren.
• De API is onvolledig sommige functies die in de manual staan zijn helemaal niet geïmplementeerd, andere staan dan weer niet in de manual.

Het zou daarom interessant zijn, mocht iemand een lijst samenstellen met de commando's samen met input/output en een relevante beschrijving (geen documentatie die automatisch is gegenereerd door een IDE).

Zolang de Lua binding niet in orde is, heeft het weinig zin een demo te geven van IdpGie omdat dit systeem hierop inwerkt.

Dit is niet enkel in het belang van IdpGie. Een (outside) gebruiker zal meestal niet de moeite nemen om een paar nachten te zoeken hoe de Lua interface werkt (en in dit geval falen). Als men van IDP een systeem wenst te maken die over enkele jaren praktische problemen oplost, kan wat openheid geen kwaad, vooral voor mensen die hier applicaties tegenaan wensen te bouwen.

[Willem Van Onsem]

Antwoord toevoegen (voor documentatie voor de volgende generatie DTAI/KRRers):

Broes en iedereen,

On 04/15/2014 08:22 AM, Broes De Cat wrote:

De documentatie van IDP ondersteund geen correct formaat bij het selecteren.

Wat bedoel je hier concreet mee? Welke documentatie (pdf of interactief?) en wat is een "correct formaat"?

Als je de pdf opent in een pdf-viewer en je selecteert tekst, dan komt daar een stroom van ongerelateerde unicode-karakters uit. Dit is niet praktisch wanneer je iets snel wil kopiëren om uit te proberen.

De API is onvolledig sommige functies die in de manual staan zijn helemaal niet geïmplementeerd, andere staan dan weer niet in de manual. Het zou daarom interessant zijn, mocht iemand een lijst samenstellen met de commando's samen met input/output en een relevante beschrijving (geen documentatie die automatisch is gegenereerd door een IDE).

Zolang de Lua binding niet in orde is, heeft het weinig zin een demo te geven van IdpGie omdat dit systeem hierop inwerkt.

De manual is inderdaad onvolledig, vooral omdat de binding zelf nog in ontwikkeling is (lees: we weten dat er vanalles nog niet goed zit, dus moet eigenlijk eerst de implementatie op punt gesteld worden voor we ons met documentatie vastpinnen).

Akkoord, maar is het mogelijk om -- eventueel automatisch -- toch een lijst van functies aan te bieden samen met de invoer- en uitvoer-types.

Men zou ook een functie kunnen aanbieden, analoog aan getoptions, getfunctions die per functie de signatuur aangeeft, samen met misschien een kleine beschrijving. Vermits in Lua alles tabellen zijn, lijkt dit een zeer geschikte taal voor meta-programming.

Voorlopig lijkt het mij voor IdpGie nuttiger om daar eens over samen te zitten dan om met IdpGie te wachten tot de Lua binding op punt staat (want daar werkt momenteel niemand aan).

Wat bedoel je met de opmerking over IDE-gegenereerde documentatie, dit is hier toch niet het geval?

Sommige documentatie is nogal "automatisch" tot stand gekomen lijkt het. Een beetje zoals je soms in een IDE ook javadoc kan genereren. Wanneer je dan een methode documenteert zoals "isGround" komt daar inderdaad iets uit als "checks if the given instance is ground.". En daar is men weinig mee, want dat kon men ook al uit de naam afleiden.

De binding hoeft niet perfect op punt te staan, indien nodig wil ik best de API aan de clientside af en toe herschrijven, maar het zou wel nuttig zijn wanneer de huidige toolkit meer toegankelijk is.

Verder zijn functie-namen zoals "clean" weinig zelfbeschrijvend. Toegegeven het is maar een naam, maar er ontstaat veel verwarring, zowel bij lezen als schrijven.

Bovendien zijn de gevolgen van bepaalde methodes evenmin duidelijk. Iets wat bijvoorbeeld niet in de manual staat is wat er zal gebeuren wanneer je eerst iets makeTrue zet en dan makeFalse. Zowel inconsistentie als revisie zijn acceptabele antwoorden, maar het staat er niet.

Concreter zou ik graag weten hoe de iterator precies werkt, en hoe ik een tabel voor één predicaat uit IDP kan halen en welke operaties toegelaten zijn op die tabel. Momenteel is het parsen/schrijven van de in- en uitvoer redelijk complex.

Excuses als de "issue" wat hard overkwam, maar is nogal onprettig om veel tijd te spenderen aan het leren begrijpen van een interface. Zeker wanneer jullie van IDP op termijn iets succesvol willen maken, zal documentatie toch een noodzakelijk kwaad zijn denk ik.

groeten, Willem