API dokümantasyon işlevi parametreleri nasıl yorumlanır?

API belgelerinde fonksiyon arayüzlerinin sözdizimini yorumlamak için bir standart var mı ve eğer evet ise nasıl tanımlanıyor?

Photoshop için "fillColor" işlevi için JavaScript komut dosyası kılavuzunda bulunan bir öğenin renginin nasıl değiştirileceğine ilişkin bir örnek:

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

Parantezlerin anlamı nedir ve parantez içinde neden virgül var? Bu, aşağıdaki örnek aramalarla nasıl ilişkilidir?

myPath.fillPath(myNewColor)

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

Öyleyse neden API belgeleri benim gibi çok yıllık yeni gelenleri / bilgisayar korsanlarını / Kendin Yapçıları karıştıracak şekilde yazılıyor?

Gerçekten bu şekilde yazılması gerekmiyor. API belgelerinde kullanım kolaylığı olmadığını kabul edeceğim. Bununla birlikte, eski manstil sözdizimi kurallarından modern API / ad alanı kurallarına pek çok geçiş vardır.

Tipik olarak, API ile çalışan kişinin türü, geliştirme konusunda biraz geçmişe veya en azından bir 'uzman kullanıcı' olacaktır. Bu tür kullanıcılar, bu tür sözdizimi kurallarına alışkındır ve yenilerini oluşturmaya çalışmaktan ziyade API belgesinin izlemesi daha mantıklıdır.

Bir yerlerde insanlara API belgelerini nasıl okuyacaklarını söyleyen gizemli bir belge var mı?

Herhangi bir yerde herhangi bir standart veya RFC süperekretsyntaxdoc yoktur, ancak yaygın olarak kullanılan UNIX kılavuz sayfası sentez formatı için ~ 30 yıllık bir dosya vardır .

Bunun bazı örnekleri (ve sorunuzu yanıtlamak) şunlar olabilir:

Altı çizili sözcükler değişmez olarak kabul edilir ve göründükleri gibi yazılır.

Bir bağımsız değişkenin etrafındaki köşeli parantezler ([]), bağımsız değişkenin isteğe bağlı olduğunu gösterir.

Elipsler ... önceki argüman-prototipin tekrar edilebileceğini göstermek için kullanılır.

Eksi işaretiyle başlayan bir argüman, bir dosya adının görünebileceği bir konumda görünse bile, genellikle bir tür bayrak argümanı anlamına gelir.

Python'dan , kılavuz sayfalarından , javascript kitaplıklarından ( Highcharts ) vb. Programlama ile ilgili neredeyse tüm dokümantasyon bu tür sözdizimi kurallarını kullanır .

Örneğinizin Adobe API'den ayrılması

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

Biz görüyoruz fillPath()(bir işlevi) İsteğe bağlı argümanlar alır fillColor, mode, opacity, preserveTransparency, feathe, wholePathveya antiAlias. Çağırarak fillPath(), bu parametrelerin hiçbirinden hiçbirine, hiçbirine geçemezsiniz. İsteğe bağlı içindeki virgül, []bu parametrenin diğerlerine ek olarak kullanılması durumunda ayırmak için virgül kullanmanız gerektiği anlamına gelir. (Sağduyu bazen, elbette, ama bazen VB gibi bazı diller, hangi parametrenin eksik olduğunu doğru bir şekilde tanımlamak için bu virgüllere açıkça ihtiyaç duyar!). Belgelere bağlantı vermediğiniz için (ve bunu Adobe'nin komut dosyası oluşturma sayfasında bulamadığım için ) Adobe API'nin hangi formatı beklediğini bilmenin bir yolu yok. Ancak, belgelerin çoğunun üst kısmında, içinde kullanılan kuralları açıklayan bir açıklama bulunmalıdır .

Bu nedenle, bu işlev muhtemelen birçok şekilde kullanılabilir:

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

Yine, API / programlama ile ilgili tüm belgelerde genellikle bazı standartlar vardır. Ancak her belgede ince farklılıklar olabilir. Uzman bir kullanıcı veya geliştirici olarak, kullanmaya çalıştığınız belgeleri / çerçeveleri / kitaplıkları okuyup anlayabilmeniz beklenmektedir.

Dinamik olarak yazılmış diller için API dokümanları, dikkatlice yazılmazlarsa çok anlamlı olmayabilir, bu yüzden çok kötü hissetmeyin, en tecrübeli geliştirici bile onları anlamaya çalışırken zorlanabilir.

Köşeli parantezler ve benzerleri hakkında, genellikle birebir örneklerin dışındaki tam kullanımı açıklayan bir kod kuralları bölümü vardır; EBNF , Regex ve Demiryolu Diyagramları neredeyse her yerde bulunmasına rağmen , çoğu gösterimi anlamak için bunlara aşina olmalısınız.

Parantezler, özelliğin isteğe bağlı olduğu anlamına gelir. Bununla birlikte, nTh seviyesinde bir özellik ayarlamak istiyorsanız, ya öncekinin özelliklerini ya da tanımsız olarak bildirmeniz gerektiğini unutmayın:

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

Aynı soruyu bir süre önce sormuştum ve birisi beni Genişletilmiş Backus-Naur Formuna yönlendirdi .

Bu mantıklıdır çünkü programlama potansiyel olarak sınırsız sonuçlar yaratmak için kullanılabilir. Dokümantasyon, her olası durum için bir örnek gösteremez. İyi bir yaygın kullanım örneği yardımcı olabilirim, ancak temeldeki sözdizimini okuyabilirseniz, kendi kodunuzu oluşturabilirsiniz.