How to properly document programming languages?

Question

Where can I find information on how to properly document a programming language? What I mean is that there seems to be a standard way to document code. php.net and api.jquery.com seem to document there code the a similar way. For example, the trim() description on php.net.

string trim  (  string $str  [,  string $charlist  ] )

And likewise on jquery.com

.animate( properties, [ duration ], [ easing ], [ callback ] )

Does anyone even know what this syntax is called?

Answer 1

That would basically be describing the method signature and using [] to indicate an optional parameter. Not sure if the [] optional param style has an official name, but PHP and Java developers usually use PHPDoc and Javadoc respectively to write inline documentation that is "auto-generated." If the parameter has a default value, it will mark the param as "optional" in the documentation. I've never seen any other documentation beside PHP.net use that style so perhaps jquery adopted it as well. A google search turns up quite a few similar tools for javascript: http://www.google.com/search?q=javascript%20documentor

Answer 2

I don’t know if there is a standard for this kind of description. But a documentation of a function/method should contain the following information:

• number, names and description of parameters (input)
• description of return value (output)
• description of what the function/method is doing

Now depending on the properties of the specific programming language, you should add more information:

• For languages with static typing and/or strong typing (like Java), you should add information about the allowed types for input and expected type for the output:

  int add(int a, int b)
  

  This prevents from using the wrong types that cause compiler or runtime errors.

• For languages that allows optional parameters (like JavaScript and PHP), you should add the information what parameters those are and what default values they have. This is often done by putting the parameter in brackets […]:

  foo(arg1[, arg2=default[, arg3=100]])
  

  For languages that allow an arbitrary number of parameters (like JavaScript and PHP), you should indicate that in the description as well.

No matter what meta syntax you use, make sure to explain it somewhere and use it consistently. And be as descriptive as possible.

Answer 3

Point to documentation standards if you will, but be warned: Open-ended discussions on this subject tend to get out of hand. A google of "documentation standard" returned a lot of hits.

Answer 4

To specify the syntax of a programming language, it is usually used a variant of the Extended Backus–Naur Form - acronym EBNF - (which is a variant of the Backus–Naur Form - acronym BNF).

I.e. EBNF and BNF are metalanguages to describe syntax of programming languages.