Seit Visual Studio 2008 gibt es die Möglichkeit, JavaScript-Funktionen so zu dokumentieren, dass auch die Intellisense in der Lage ist, Informationen anzuzeigen. Um so erstaunter bin ich jedes Mal, noch häufig auf Konstrukte wie diese hier zu stoßen:
// function that implements some magic
function DoSomething(parameter) {
}
Der Versuch ist ganz gut, aber es geht noch besser. Nachteil dieser Art der Dokumentation ist nämlich, dass Intellisense dann genau auch nur die Methodensignatur anzeigt, nicht aber nähere Informationen zur Methode.
Mit nur einer kleinen Umstellung kann man diese Unterstützung aktivieren:
function DoSomething(parameter) {
/// <summary>
/// function that implements some magic
/// </summary>
/// <param name="parameter">the dom element's id</param>
}
Was auffällt: Der Aufbau der Dokumentation ist dem was wir schon für C#-Funktionen kennen sehr ähnlich. Einziger Unterschied: In C# wird der Kommentar über die Methode geschrieben und hier in die Methode. Ab diesem Zeitpunkt ist Visual Studio in der Lage, die Informationen wie gewohnt auch schon während des Tippens anzuzeigen.
Wie schon beschrieben ähnelt der Aufbau sehr dem, was man schon von der Dokumentation in C# kennt - es sollte also keine zu große Einstiegshürden für Entwickler geben. Wer eine kurze Einführung braucht, dem sei der Blogpost von Bertrand Le Roy ans Herz gelegt.