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

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

---

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 문서는 신중하게 작성하지 않으면 그다지 의미가 없을 수 있으므로 너무 나쁘게 느끼지 마십시오. 가장 노련한 개발자라도 이해하는 데 어려움을 겪을 수 있습니다.

About brackets and such, there is usually a code conventions section that should explain the exact usage outside literal examples; although EBNF, Regex and Railroad Diagrams are almost ubiquitous, so you should be familiar with them to understand most notations.

---

The brackets mean that the property is optional. Be aware though that if you want to set soem property at the nTh rank, you have to either declare properties for the eading one or declare them as undefined :

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

Loic http://www.loicaigon.com

---

I had this same question a while back and somebody pointed me to Extended Backus–Naur Form.

It makes sense because programming can be used to create potentially limitless outcomes. The documentation can not display an example for every possible case. A good example of common use I helpful but once you can read the underlying syntax you are able to create your own code.

참고URL : https://stackoverflow.com/questions/10925478/how-to-interpret-api-documentation-function-parameters