[api] API 문서 함수 매개 변수를 해석하는 방법은 무엇입니까?

Program / 글쓴이

API 문서에서 함수 인터페이스의 구문을 해석하는 표준이 있습니까? 그렇다면 어떻게 정의됩니까?

다음은 “fillColor”함수에 대한 Photoshop 용 JavaScript 스크립팅 가이드의 항목 색상을 변경하는 방법에 대한 예입니다.

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

대괄호의 의미는 무엇이며 대괄호 안에 쉼표가있는 이유는 무엇입니까? 이것이 다음 예제 호출과 어떤 관련이 있습니까?

myPath.fillPath(myNewColor)

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

답변

그렇다면 API 문서는 왜 저와 같은 다년생 뉴스 / 해커 / DIYers를 혼동하는 방식으로 작성됩니까?

실제로 그렇게 쓰여지는 것은 아닙니다. API 문서 전반에 걸쳐 사용하기가 쉽지 않다는 데 동의합니다. 그러나 이전 man스타일 구문 규칙에서 최신 API / 네임 스페이스 규칙 으로 많은 교차가 있습니다 .

일반적으로 API를 사용하는 유형의 사람은 개발에 대한 배경 지식이 있거나 적어도 ‘파워 유저’입니다. 이러한 유형의 사용자는 이러한 구문 규칙에 익숙하며 새 문서를 작성하는 것보다 API 문서가 따르는 것이 더 합리적입니다.

사람들에게 API 문서를 읽는 방법을 알려주는 신비한 문서가 어딘가에 있습니까?

표준 또는 RFC supersekretsyntaxdoc은 어디에도 배치되어 있지 않지만 널리 사용되는 UNIX man 페이지 구문 형식에 대한 ~ 30 년 된 파일 이 있습니다.

이에 대한 몇 가지 예 (및 귀하의 질문에 답변)는 다음과 같습니다.

밑줄이 그어진 단어는 리터럴로 간주되며 표시되는대로 입력됩니다.

인수 주위의 대괄호 ([])는 인수가 선택 사항임을 나타냅니다.

생략 부호 …는 이전 인수 프로토 타입이 반복 될 수 있음을 표시하는 데 사용됩니다.

빼기 기호-로 시작하는 인수는 파일 이름이 나타날 수있는 위치에 나타나더라도 일종의 플래그 인수를 의미하는 경우가 많습니다.

거의 모든 프로그래밍 관련 문서는 Python , man pages , javascript libs ( Highcharts ) 등에서 이러한 유형의 구문 규칙을 사용합니다 .

Adobe API에서 예제 분석

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

우리는 볼 fillPath()(함수) 선택적 인수한다 fillColor, mode, opacity, preserveTransparency, feathe, wholePath또는 antiAlias. 를 호출 fillPath()하면 해당 매개 변수를 없음에서 모두로 전달할 수 있습니다. 선택 사항 내의 쉼표 []는이 매개 변수가 다른 매개 변수와 함께 사용되는 경우이를 구분하기 위해 쉼표가 필요함을 의미합니다. (당연히 상식적인 경우도 있지만 VB와 같은 일부 언어에서는 누락 된 매개 변수를 적절하게 설명하기 위해 이러한 쉼표가 명시 적으로 필요합니다!) 문서에 링크하지 않았기 때문에 (그리고 Adobe의 스크립팅 페이지 에서 찾을 수 없습니다 ) 실제로 Adobe API가 어떤 형식을 기대하는지 알 수있는 방법이 없습니다. 그러나 대부분의 문서 맨 위에 사용 된 규칙을 설명 하는 설명이 있어야합니다 .

따라서이 함수는 여러 가지 방법으로 사용될 수 있습니다.

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

다시 말하지만 일반적으로 API / 프로그래밍과 관련된 모든 문서에는 몇 가지 표준이 있습니다. 그러나 각 문서에는 미묘한 차이가있을 수 있습니다. 고급 사용자 또는 개발자는 사용하려는 문서 / 프레임 워크 / 라이브러리를 읽고 이해할 수 있어야합니다.

답변

동적 유형 언어에 대한 API 문서는 신중하게 작성하지 않으면 그다지 의미가 없을 수 있으므로 너무 나쁘게 느끼지 마십시오. 가장 노련한 개발자라도 이해하는 데 어려움을 겪을 수 있습니다.

대괄호 등에 대해서는 일반적으로 리터럴 예제 외부에서 정확한 사용법을 설명해야하는 코드 규칙 섹션이 있습니다. 하지만 EBNF , 정규식 및 철도 다이어그램은 거의 유비 쿼터스, 그래서 당신은 대부분의 표기법을 이해하는 그들에 대해 잘 알고 있어야합니다.

답변

대괄호는 속성이 선택 사항임을 의미합니다. nTh 순위에서 일부 속성을 설정하려면 선행 속성에 대한 속성을 선언하거나 정의되지 않은 것으로 선언해야합니다.

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

답변

나는 이와 같은 질문을 얼마 전에 받았는데 누군가가 나를 Extended Backus–Naur Form으로 안내했습니다 .

프로그래밍을 사용하여 잠재적으로 무한한 결과를 만들 수 있기 때문에 의미가 있습니다. 문서는 모든 가능한 경우에 대한 예제를 표시 할 수 없습니다. 일반적인 사용의 좋은 예는 도움이되었지만 기본 구문을 읽을 수 있으면 자신 만의 코드를 만들 수 있습니다.

답변