JavaDoc documentatie: hoe parameter JSON object documenteren

[Rekcor]

Om mijn (PHP/Javascript) code te documenteren, gebruik ik de 'JavaDoc'-manier, bijv.

JavaScript:

/**
 * Tells all listeners an event has occured
 * @param {string} type The event, e.g. 'onclick', 'onselect' etc
 * @returns {boolean} True if all assigned functions return undefined or true, false if one of them returns false
 **/
function fireEvent(type){
  return this.eventListenerFactory.fire(type,  arguments);
}

Met name in Javascript komt het nogal eens voor dat een argument een JSON-object bevat. Dit JSON-object moet dan wel een bepaalde structuur hebben, en die structuur wil ik graag documenteren. Dit valt nog niet mee, en daarom mijn vraag: hoe doen jullie dit?

Zouden jullie bijvoorbeeld blij worden van deze documentatie?

JavaScript:

/**
 * Adds a form template
 * @param {object} templateJSON  The form html template: {"formSectionName":
 *                                                         {"html"     : string, //the form template
 *                                                          "settings" :
 *                                                           {"elementName"      : string, //the corresponding name in the formHTML template, without (!) %portName% so <input name="%portName%Description" type="text" /> in the template would get "Description"
 *                                                            "oneCharacterName" : string, //unique name consisting of one character [a-z|A-Z|0-9]; if provided, this name will be posted in the form
 *                                                            "type"             : string  //the value type: 'integer', 'float', 'string'
 *                                                           }
 *                                                         }
 *                                                       }
 */
 function addTemplate(templateJSON){

 }

[Woy]

Rekcor schreef op donderdag 29 juli 2010 @ 12:41:
Dit JSON-object moet dan wel een bepaalde structuur hebben, en die structuur wil ik graag documenteren

Is het niet handiger om een TypeName aan een dergelijke parameter te hangen, en die ergens anders te documenteren. Dat is ook handig omdat je het type dan opnieuw kunt gebruiken.

Dat je het type niet ergens expliciet definieert zegt natuurlijk niet dat je het niet als zodanig kunt behandelen.

[Rekcor]

Woy schreef op donderdag 29 juli 2010 @ 12:44:
[...]

Is het niet handiger om een TypeName aan een dergelijke parameter te hangen, en die ergens anders te documenteren. Dat is ook handig omdat je het type dan opnieuw kunt gebruiken.

Dat je het type niet ergens expliciet definieert zegt natuurlijk niet dat je het niet als zodanig kunt behandelen.

Eh... hoe moet ik dat voor me zien?

[.oisyn]

Woy schreef op donderdag 29 juli 2010 @ 12:44:
[...]

Is het niet handiger om een TypeName aan een dergelijke parameter te hangen, en die ergens anders te documenteren. Dat is ook handig omdat je het type dan opnieuw kunt gebruiken.

Dat gaat natuurlijk niet echt, omdat dat type nergens specifiek wordt gedefinieerd in code (waar je dan vervolgens de javadoc documentatie bij zou zetten)

[Woy]

.oisyn schreef op donderdag 29 juli 2010 @ 13:06:
[...]

Dat gaat natuurlijk niet echt, omdat dat type nergens specifiek wordt gedefinieerd in code (waar je dan vervolgens de javadoc documentatie bij zou zetten)

Dat zeg ik toch ook

Dat je het type niet ergens expliciet definieert zegt natuurlijk niet dat je het niet als zodanig kunt behandelen.

Je kunt gewoon ergens alleen een stukje documentatie opnemen, waar je in je method definitie gewoon naar verwijst.

JavaScript:

/** @@Type: Template
  * {"formSectionName": 
  *     {"html"     : string, //the form template 
  *      "settings" : 
  *         { "elementName"      : string, //the corresponding name in the formHTML template, without (!) %portName% so <input name="%portName%Description" type="text" /> in the template would get "Description" 
  *           "oneCharacterName" : string, //unique name consisting of one character [a-z|A-Z|0-9]; if provided, this name will be posted in the form 
  *           "type"             : string  //the value type: 'integer', 'float', 'string' 
  *         } 
  *     } 
  * }
 **/

....
/**
 * Adds a form template
 * @param {Template} templateJSON  The form html template
 */
 function addTemplate(templateJSON){

 }

Het nadeel is natuurlijk dat je informatie over meerdere plekken verspreid staat, echter vervuilt het opnemen van de type informatie in de methode documentatie ook die documentatie weer.

[ Voor 6% gewijzigd door Woy op 29-07-2010 13:17 ]

[.oisyn]

Woy schreef op donderdag 29 juli 2010 @ 13:16:
[...]

Dat zeg ik toch ook

Dat vond ik een heel onduidelijke zin en ik ken javadoc wat dat betreft ook niet goed genoeg

[Woy]

.oisyn schreef op donderdag 29 juli 2010 @ 13:28:
[...]

Dat vond ik een heel onduidelijke zin en ik ken javadoc wat dat betreft ook niet goed genoeg

Ik ken JavaDoc verder ook niet, maar de naam doet me vermoeden dat het vooral voor Java bedacht is, en dan kan ik me voorstellen dat daar niet in dit soort contructies voorzien is.

Ik heb ook geen ervaring met dit soort dingen documenteren, wat ik opper is gewoon mijn eerste ingeving. Aan de ene kant is het handig om direct alle gegevens bij de hand te hebben, alleen bij wat complexere structuren kan ik me voorstellen dat het er onoverzichtelijk door word, en dus is het IMHO handiger om het ergens anders te documenteren.

[.oisyn]

Lekker is dat, alle javadoc documentatie links op Oracle zijn dood
http://java.sun.com/j2se/...oldocs/javadoc/index.html

.edit: ah, dit is de correcte url: http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/index.html

[ Voor 27% gewijzigd door .oisyn op 29-07-2010 13:41 ]

[Rekcor]

Bedankt voor de reacties! Het idee van Woy spreekt me wel aan: momenteel los ik dit op door het object in een (1) functie te documenteren, en naar die functie te verwijzen met {@link } zodra het object ergens anders gebruikt wordt.