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

103

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
})
Dbonneville
fonte
4
Existe uma introdução ao documento de referência da API que descreve suas convenções sintáticas?
Greg Hewgill
35
Para a pessoa que votou para fechar: Eu acredito que esta questão tem mérito e "votaria para não fechar" se pudesse. Não é uma pergunta que eu já vi (ou ouvi) ser feita antes, ela aborda um problema legítimo relacionado à programação e eu pessoalmente consideraria a resposta útil quando ensino coisas relacionadas à programação às pessoas.
David Wolever
4
Derek: Acho que você perdeu uma das frases em negrito da postagem original. Se você pesquisar no Google "como ler a documentação da API", as informações nos primeiros 10 resultados dizem coisas como "abstrato", "incompleto", "confuso" etc., reforçando assim o ponto da minha pergunta.
dbonneville
2
Greg: Não há introduções aos produtos Photoshop / Adobe. Todos eles seguem o mesmo formato em 2 PDFs por produto. As outras APIs nas quais estou pensando fazem o mesmo. Há um conhecimento implícito que em muitos casos não tenho e certamente gostaria de ter.
dbonneville
1
Um recurso útil é o visualizador de objeto integrado ao IDE Extendscript (pressione F1). Clicar em um objeto mostrará quais propriedades e métodos ele possui. Além disso, se ele usa outros objetos como parâmetros, (geralmente) vincula a eles para que você possa ver quais propriedades eles também têm. Não é perfeito, mas ajuda.
pdizz de

Respostas:

92

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.

PenguinCoder
fonte
5
O link de formato de sinopse da página de manual do UNIX está morto - alguém tem um link de substituição? @PenguinCoder Update: Baseado em [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange), é vagamente baseado em [ en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_Form (EBNF)
steviejay
Há uma cópia arquivada do formato de sinopse da página do manual
CodeManX
5

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.

Fortran
fonte
3

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
Loic Aigon
fonte
2
fillPath (mode)pode estar ok. Se um argumento opcional vier antes de um não opcional, geralmente significa que a função é inteligente o suficiente para detectar se o argumento opcional foi fornecido ou não (por exemplo, olhando para seu tipo)
ThiefMaster
1
MMmm bem, isso é possível, mas eu prefiro confiar em algo forte do que algo que o script possa fazer por mim: D
Loic Aigon
1

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.

StevenKW
fonte