Làm thế nào để diễn giải các tham số chức năng tài liệu API?

Có tiêu chuẩn nào để diễn giải cú pháp của giao diện hàm trong tài liệu API không và nếu có, nó được định nghĩa như thế nào?

Dưới đây là một ví dụ về cách thay đổi màu sắc của một mục, hướng dẫn tạo tập lệnh JavaScript cho Photoshop cho hàm "fillColor":

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

Nêu ý nghĩa của dấu ngoặc và tại sao lại có dấu phẩy trong dấu ngoặc? Điều này liên quan như thế nào đến các cuộc gọi ví dụ sau đây?

myPath.fillPath(myNewColor)

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

Vậy tại sao tài liệu API lại được viết theo cách gây nhầm lẫn cho những người mới làm việc lâu năm / hacker / DIYers như tôi?

Nó thực sự không được viết theo cách đó. Tôi đồng ý rằng dường như không có sự dễ sử dụng trên các tài liệu API. Tuy nhiên, có rất nhiều sự thay đổi từ các manquy ước cú pháp kiểu cũ hơn sang các quy ước không gian tên / API hiện đại.

Thông thường, kiểu người làm việc với API, sẽ có một số nền tảng về phát triển hoặc ít nhất là một 'người dùng thành thạo'. Những kiểu người dùng này đã quen với các quy ước cú pháp như vậy và điều đó có ý nghĩa hơn khi tài liệu API tuân theo hơn là cố gắng tạo những quy ước mới.

Có tài liệu bí ẩn nào đó ở đâu đó cho mọi người biết cách đọc tài liệu API không?

Thực sự không có tiêu chuẩn, hoặc RFC, supersekretsyntaxdoc đặt xung quanh mọi nơi, tuy nhiên có một tệp đã ~ 30 năm tuổi cho định dạng tổng hợp trang đàn ông UNIX đang được sử dụng rộng rãi.

Một số ví dụ về điều này (và trả lời câu hỏi của bạn) sẽ là:

Các từ được gạch chân được coi là nghĩa đen và được nhập ngay khi chúng xuất hiện.

Dấu ngoặc vuông ([]) xung quanh một đối số cho biết rằng đối số là tùy chọn.

Dấu ba chấm ... được sử dụng để cho thấy rằng đối số-nguyên mẫu trước đó có thể được lặp lại.

Đối số bắt đầu bằng dấu trừ - thường được coi là đối số cờ nào đó ngay cả khi nó xuất hiện ở vị trí mà tên tệp có thể xuất hiện.

Hầu hết tất cả các tài liệu liên quan đến lập trình đều sử dụng loại quy ước cú pháp này, từ Python , man pages , javascript libs ( Highcharts ), v.v.

Chia nhỏ ví dụ của bạn từ Adobe API

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

Chúng ta thấy rằng fillPath()(một hàm) nhận các đối số tùy chọn fillColor, mode, opacity, preserveTransparency, feathe, wholePathhoặc antiAlias. Gọi fillPath(), bạn có thể chuyển bất cứ nơi nào từ không có, cho tất cả, các tham số đó cho nó. Các dấu phẩy trong tùy chọn []có nghĩa là nếu tham số này được sử dụng cùng với các tham số khác, bạn cần dấu phẩy để phân tách nó. (Chắc chắn, thông thường đôi khi, nhưng đôi khi một số ngôn ngữ như VB, cần rõ ràng những dấu phẩy đó để phân định chính xác tham số nào bị thiếu!). Vì bạn không liên kết đến tài liệu (và tôi không thể tìm thấy nó trên trang kịch bản của Adobe ) nên thực sự không có cách nào để biết định dạng mà Adobe API đang mong đợi. Tuy nhiên, cần có phần giải thích ở đầu hầu hết các tài liệu giải thích các quy ước được sử dụng bên trong.

Vì vậy, chức năng này có thể được sử dụng theo nhiều cách:

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

Một lần nữa, thường có một số tiêu chuẩn trên tất cả các tài liệu liên quan đến API / lập trình. Tuy nhiên trong mỗi tài liệu, có thể có sự khác biệt nhỏ. Là một người dùng thành thạo hoặc một nhà phát triển, bạn ĐƯỢC mong đợi có thể đọc và hiểu các tài liệu / khuôn khổ / thư viện mà bạn đang cố gắng sử dụng.

Tài liệu API cho các ngôn ngữ được nhập động có thể không có nhiều ý nghĩa nếu không được viết cẩn thận, vì vậy đừng quá tệ về nó, ngay cả những nhà phát triển dày dặn nhất cũng có thể gặp khó khăn khi cố gắng hiểu chúng.

Về dấu ngoặc và như vậy, thường có một phần quy ước mã sẽ giải thích cách sử dụng chính xác bên ngoài các ví dụ theo nghĩa đen; mặc dù EBNF , Regex và Sơ đồ đường sắt gần như phổ biến, vì vậy bạn nên làm quen với chúng để hiểu hầu hết các ký hiệu.

Các dấu ngoặc có nghĩa là thuộc tính là tùy chọn. Hãy lưu ý rằng nếu bạn muốn đặt một số thuộc tính ở thứ hạng nTh, bạn phải khai báo thuộc tính cho thuộc tính đứng đầu hoặc khai báo chúng là không xác định:

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

Tôi đã có cùng câu hỏi này một thời gian trước và ai đó đã chỉ tôi đến Dạng Backus-Naur mở rộng .

Nó có ý nghĩa bởi vì lập trình có thể được sử dụng để tạo ra các kết quả tiềm năng vô hạn. Tài liệu không thể hiển thị ví dụ cho mọi trường hợp có thể xảy ra. Một ví dụ điển hình về cách sử dụng phổ biến, tôi hữu ích nhưng khi bạn có thể đọc cú pháp cơ bản, bạn có thể tạo mã của riêng mình.