code-documentation


Why programming documentation has square brackets and commas in weird places?


Why in various programming documentation for functions do they have square brackets around parameters, but they are ordered such that the later parameters seem to be subsets of the first? Or if the brackets in that language delineate arrays it's as if the second parameter is supposed to be inside of the array of the first, but often the parameters are not even supposed to be arrays, and also they have commas in weird places.
I've seen this style all over the place and tried to find some place where it is written down why they do this. Maybe someone just arbitrarily decided on that and other programmers thought, "oh that looks cool, I'll try that in writing my own documentation.."
Or maybe there is some big book of rules for how to make programming docs? If so I'd like to know about it.
Here is an example: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice
if you go to the link in the blue box near the top of the page right bellow the h2? heading "syntax" it says this: arr.slice([begin[, end]]) meaning that the first parameter is begin, and the next parameter is end, for the slice method. When you first see something like this it looks like the brackets and commas are randomly placed.. but they do it all over the place and the same way. There must be some method to the madness!
Brackets around a parameter name indicate that it is an optional parameter. E.g. you can call the slice method without an end parameter. This is just a general rule of language syntax documentation, square brackets indicate optional words/tokens.

Related Links

Why programming documentation has square brackets and commas in weird places?

Categories

HOME
batch-file
eclipse
codenvy
ng-idle
github-for-windows
numbers
composite-primary-key
graphics
spring-data-mongodb
simulink
mapbox
retrofit2
teechart
little-proxy
openstreetmap
endeca
x-cart
rtf
zerobrane
heat
symbol
screen-readers
capistrano3
google-content-api
sencha-touch
symbols
guzzle
springfox
libigl
roslyn
gmock
entity-relationship-model
carrierwave
winpe
corenlp-server
scrollview
autodesk-designautomation
xbox
testbed
kodi
fstream
clickjacking
raft
google-earth-engine
jvmti
apache-stanbol
preloader
file-sharing
procfile
nanoc
qtranslate
compiler-design
colorbar
django-1.10
android-instrumentation
myspace
iotivity
resourcemanager
refinerycms
redis-cluster
contentcontrol
mobiledoc-kit
dynamics-nav-2016
wiredep
oracle-spatial
forwarding
rate-limiting
coda
ocra
infosphere-spl
jbake
cocos3d
xml-namespaces
tinyxml
jquery-slider
dct
menubar
artemis
kendo-dataviz
modular
wp7test
joomla3.1
frameworkelementfactory
web-farm
paginator
subproject
fusefabric
cross-database
event-receiver
xui
django-paypal
luajava
commerceserver2007
ie-compatibility-mode
silent
drupal-fivestar
binomial-heap
message-passing
filesystemobject
firefox-3
contentpresenter

Resources

Encrypt Message