Function documentation

[Becheler]

I propose to standardize the documentation for functions, according to the model proposed in this website : https://google-styleguide.googlecode.com/svn/trunk/Rguide.xml#functiondefinition

Functions should contain a comments section immediately below the function definition line. These comments should consist of a one-sentence description of the function; a list of the function's arguments, denoted by Args:, with a description of each (including the data type); and a description of the return value, denoted by Returns:. The comments should be descriptive enough that a caller can use the function without reading any of the function's code. An exemple :

CalculateSampleCovariance <- function(x, y, verbose = TRUE) {
  # Computes the sample covariance between two vectors.
  #
  # Args:
  #   x: One of two vectors whose sample covariance is to be calculated.
  #   y: The other vector. x and y must have the same length, greater than one,
  #      with no missing values.
  #   verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE.
  #
  # Returns:
  #   The sample covariance between x and y.
  n <- length(x)
  # Error handling
  if (n <= 1 || n != length(y)) {
    stop("Arguments x and y have different lengths: ",
         length(x), " and ", length(y), ".")
  }
  if (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {
    stop(" Arguments x and y must not have missing values.")
  }
  covariance <- var(x, y)
  if (verbose)
    cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
  return(covariance)
}

What do you think ?

[stdupas]

Bonne idée Arnaud, il faut évoluer vers une bibliothèque et les fonction d'une bibliothèque doivent nécessairement comprendre la descritpion des tous les arguments valeurs, un titre et une description générale, ainsi qu'un exemple qui doit marcher tout seul. Le constructeur de bibliothèque vérifie tout cela. Sinon c'est quoi ce truc?

Returns:

The sample covariance between x and y.

n <- length(x)

Error handling

[Becheler]

Cool je peux arreter de me la péter en parlant (mal) anglais ! :D Heu je crois que pour l'exemple on s'arrêter après la description de Returns. n <- lenght(x) fait partie de l'initialisation de la fonction je suppose. Oki, je charge pas trop la mule des commentaires pour l'instant, là ça me sert aussi et surtout à débroder le code et les fonctions :)