Como interpretar os parâmetros da função de documentação da API?

Existe um padrão para interpretar a sintaxe das interfaces de função em documentações de API e, em caso afirmativo, como é definido?

Aqui está um exemplo de como alterar a cor de um item do guia de script JavaScript para Photoshop para a função "fillColor":

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

Qual é o significado dos colchetes e por que existem vírgulas entre os colchetes? Como isso se relaciona com as chamadas de exemplo a seguir?

myPath.fillPath(myNewColor)

myPath.fillPath(mynewColor, {
    mode: RGB,
    opacity: .5
})

Então, por que a documentação da API é escrita de forma a confundir newbs / hackers / DIYers perenes como eu?

Realmente não foi feito para ser escrito dessa forma. Concordo que parece não haver facilidade de uso nas documentações de API. No entanto, há muitos cruzamentos das manconvenções de sintaxe de estilo mais antigo para as convenções modernas de API / namespace.

Normalmente, o tipo de pessoa que trabalha com API, terá alguma experiência em desenvolvimento ou pelo menos um 'usuário avançado'. Esses tipos de usuários estão acostumados com essas convenções de sintaxe e faz mais sentido seguir o documento da API do que tentar criar novos.

Existe algum documento misterioso em algum lugar que diga às pessoas como ler a documentação da API?

Realmente não há supersekretsyntaxdoc padrão, ou RFC, em qualquer lugar, no entanto, há um arquivo de aproximadamente 30 anos para o formato de sintaxe de página de manual do UNIX que é de uso generalizado.

Alguns exemplos disso (e de resposta à sua pergunta) seriam:

Palavras sublinhadas são consideradas literais e são digitadas exatamente como aparecem.

Os colchetes ([]) em torno de um argumento indicam que o argumento é opcional.

Reticências ... são usadas para mostrar que o protótipo de argumento anterior pode ser repetido.

Um argumento que começa com um sinal de menos - é freqüentemente considerado como algum tipo de argumento de sinalizador, mesmo se aparecer em uma posição onde um nome de arquivo possa aparecer.

Quase toda a documentação relacionada à programação usa este tipo de convenção de sintaxe, de Python , páginas de manual , bibliotecas javascript ( Highcharts ), etc.

Descrevendo seu exemplo da API Adobe

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

Vemos que fillPath()(uma função) recebe argumentos opcionais fillColor, mode, opacity, preserveTransparency, feathe, wholePathou antiAlias. Chamando fillPath(), você poderia passar de nenhum a todos esses parâmetros para ele. As vírgulas dentro do opcional []significam que, se este parâmetro for usado além de outros, você precisará da vírgula para separá-lo. (O bom senso às vezes, com certeza, mas às vezes algumas linguagens como VB, explicitamente precisam dessas vírgulas para delinear corretamente qual parâmetro está faltando!). Como você não vinculou a documentação (e não consigo encontrar na página de script da Adobe ), não há realmente uma maneira de saber qual formato a API da Adobe está esperando. No entanto, deve haver uma explicação no início da maioria da documentação explicando as convenções usadas.

Portanto, esta função provavelmente poderia ser usada de várias maneiras:

fillPath() //Nothing passed
fillPath(#000000,RGB) // Black, in RGB mode
fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity

//Now it gets tricky, this might ALSO be acceptable:
fillPath(#000000,50) // Black, no mode, half opacity

//OR
fillPath(#000000,,50) // Black, no mode, half opacity

Novamente, geralmente existem alguns padrões em todas as documentações relacionadas à API / programação. No entanto, em cada documento, pode haver diferenças sutis. Como um usuário avançado ou desenvolvedor, espera-se que você seja capaz de ler e compreender os documentos / estruturas / bibliotecas que está tentando usar.

Documentos de API para linguagens digitadas dinamicamente podem não ser muito significativos se não forem escritos com cuidado, então não se sinta mal com isso, mesmo o desenvolvedor mais experiente pode ter dificuldade em tentar entendê-los.

Sobre colchetes e coisas assim, geralmente há uma seção de convenções de código que deve explicar o uso exato fora dos exemplos literais; embora EBNF , Regex e Diagramas de Ferrovia sejam quase onipresentes, você deve estar familiarizado com eles para entender a maioria das notações.

Os colchetes significam que a propriedade é opcional. No entanto, esteja ciente de que, se quiser definir alguma propriedade na classificação nTh, você deve declarar as propriedades para a primeira ou declará-las como indefinidas:

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

Eu tive essa mesma pergunta um tempo atrás e alguém me indicou o Extended Backus-Naur Form .

Faz sentido porque a programação pode ser usada para criar resultados potencialmente ilimitados. A documentação não pode mostrar um exemplo para todos os casos possíveis. Um bom exemplo de uso comum é útil, mas uma vez que você possa ler a sintaxe subjacente, você será capaz de criar seu próprio código.