เหตุใดเอกสาร API จึงเขียนในลักษณะที่สร้างความสับสนให้กับมือใหม่ / แฮกเกอร์ / DIYers ยืนต้นเช่นตัวฉันเอง
มันไม่ได้ตั้งใจจะเขียนแบบนั้น ฉันยอมรับว่าดูเหมือนว่าจะไม่มีความสะดวกในการใช้งานในเอกสาร API อย่างไรก็ตามมีการข้ามmanรูปแบบไวยากรณ์แบบเก่าไปจนถึงอนุสัญญา API / เนมสเปซสมัยใหม่มากมาย
โดยปกติแล้วคนประเภทที่ทำงานกับ API จะมีพื้นฐานในการพัฒนาหรืออย่างน้อยก็เป็น 'ผู้ใช้ระดับสูง' ผู้ใช้ประเภทนี้ใช้ในรูปแบบไวยากรณ์ดังกล่าวและเหมาะสมกว่าสำหรับเอกสาร API ที่จะปฏิบัติตามมากกว่าที่จะพยายามสร้างใหม่
มีเอกสารลึกลับที่ไหนสักแห่งที่บอกวิธีอ่านเอกสาร API ของผู้คนหรือไม่
ไม่มีมาตรฐานหรือ RFC supersekretsyntaxdoc วางอยู่ทั่วทุกที่ แต่มีไฟล์อายุประมาณ 30 ปีสำหรับรูปแบบการซิงโครไนซ์ของ UNIX man pageซึ่งใช้กันอย่างแพร่หลาย
ตัวอย่างบางส่วนของสิ่งนี้ (และการตอบคำถามของคุณ) ได้แก่ :
คำที่ขีดเส้นใต้ถือเป็นตัวอักษรและพิมพ์ตามที่ปรากฏ
วงเล็บเหลี่ยม ([]) รอบอาร์กิวเมนต์ระบุว่าอาร์กิวเมนต์เป็นทางเลือก
วงรี ... ใช้เพื่อแสดงว่าอาร์กิวเมนต์ - ต้นแบบก่อนหน้านี้อาจถูกทำซ้ำ
อาร์กิวเมนต์ที่ขึ้นต้นด้วยเครื่องหมายลบมักถูกนำมาใช้เพื่อหมายถึงอาร์กิวเมนต์แฟล็กบางประเภทแม้ว่าจะปรากฏในตำแหน่งที่สามารถแสดงชื่อไฟล์ได้ก็ตาม
เอกสารที่เกี่ยวข้องกับการเขียนโปรแกรมเกือบทั้งหมดใช้รูปแบบไวยากรณ์ประเภทนี้ตั้งแต่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 / การเขียนโปรแกรม อย่างไรก็ตามในแต่ละเอกสารอาจมีความแตกต่างเล็กน้อย ในฐานะผู้ใช้ระดับสูงหรือนักพัฒนาคุณคาดว่าจะสามารถอ่านและทำความเข้าใจเอกสาร / เฟรมเวิร์ก / ไลบรารีที่คุณพยายามใช้