Bu belge, Google'ın Kotlin Programlama Dili'nde kaynak koda yönelik Android kodlama standartlarının tam tanımıdır. Bir Kotlin kaynak dosyasının, yalnızca buradaki kurallara uyması halinde Google Android Stili'nde olduğu kabul edilir.
Diğer programlama stili kılavuzları gibi, ele alınan konular yalnızca estetik biçimlendirme sorunlarını değil, diğer kural türlerini veya kodlama standartlarını da kapsar. Ancak, bu belge esas olarak evrensel olarak uyguladığımız kesin ve hızlı kurallara odaklanmaktadır ve açıkça uygulanabilir olmayan (insan veya araç tarafından) tavsiyeler vermekten kaçınır.
Kaynak dosyalar
Tüm kaynak dosyalar UTF-8 olarak kodlanmalıdır.
Adlandırma
Kaynak dosya yalnızca tek bir üst düzey sınıf içeriyorsa dosya adı, büyük/küçük harfe duyarlı adı ve .kt
uzantısını yansıtmalıdır. Aksi takdirde, bir kaynak dosyada birden çok üst düzey bildirim varsa dosyanın içeriğini tanımlayan bir ad seçin, PascalCase'i (dosya adı çoğulsa CamelCase kabul edilebilir) uygulayın ve .kt
uzantısını ekleyin.
// MyClass.kt class MyClass { }
// Bar.kt class Bar { } fun Runnable.toBar(): Bar = // …
// Map.kt fun <T, O> Set<T>.map(func: (T) -> O): List<O> = // … fun <T, O> List<T>.map(func: (T) -> O): List<O> = // …
// extensions.kt fun MyClass.process() = // … fun MyResult.print() = // …
Özel Karakterler
Boşluk karakterleri
Satır sonlandırıcı sırası dışında, kaynak dosyanın herhangi bir yerinde görünen tek boşluk karakteri ASCII yatay boşluk karakteri (0x20) şeklindedir. Bunun anlamı şudur:
- Dize ve karakter sabit değerlerindeki diğer tüm boşluk karakterlerine çıkış yapılır.
- Girinti için sekme karakterleri kullanılmaz.
Özel kaçış dizileri
Özel bir kaçış dizisi olan tüm karakterler (\b
, \n
, \r
, \t
, \'
, \"
, \\
ve \$
) için karşılık gelen Unicode (ör. \u000a
) kod dışı bırakın.
ASCII olmayan karakterler
Kalan ASCII olmayan karakterler için gerçek Unicode karakteri (ör. ∞
) veya eşdeğer Unicode çıkışı (ör. \u221e
) kullanılır.
Yapacağınız seçim yalnızca kodun hangi kodun daha kolay okunup anlaşıldığına bağlıdır.
Unicode çıkışları, herhangi bir konumda yazdırılabilir karakterler için önerilmez ve dize değişmez değerleri ve yorumları dışında kesinlikle önerilmez.
Örnek | Tartışma |
---|---|
val unitAbbrev = "μs" |
En iyi: Yorum yapmasa bile tamamen anlaşılır. |
val unitAbbrev = "\u03bcs" // μs |
Kötü: Yazdırılabilir bir karakter içeren kaçış karakteri kullanmak için hiçbir neden yoktur. |
val unitAbbrev = "\u03bcs" |
Kötü: Okuyucunun bunun ne olduğunu bilmiyor. |
return "\ufeff" + content |
İyi: Yazdırılamayan karakterler için çıkış karakterleri kullanın ve gerekiyorsa yorum yapın. |
Yapı
.kt
dosyası sırasıyla aşağıdaki öğelerden oluşur:
- Telif hakkı ve/veya lisans başlığı (isteğe bağlı)
- Dosya düzeyinde ek açıklamalar
- Paket özeti
- Ekstreleri içe aktar
- Üst düzey beyanlar
Bu bölümlerin her biri tam olarak tek bir boş satırla ayrılır.
Telif Hakkı / Lisans
Bir telif hakkı veya lisans başlığı dosyaya aitse çok satırlı yorumun hemen en üstüne yerleştirilmelidir.
/* * Copyright 2017 Google, Inc. * * ... */
KDoc stili veya tek satır stili bir yorum kullanmayın.
/** * Copyright 2017 Google, Inc. * * ... */
// Copyright 2017 Google, Inc. // // ...
Dosya düzeyinde ek açıklamalar
"file" use-site target değerine sahip ek açıklamalar, herhangi bir başlık yorumu ile paket bildirimi arasına yerleştirilir.
Paket özeti
Paket ifadesi herhangi bir sütun sınırına tabi değildir ve hiçbir zaman satıra sarmalanmaz.
Ekstreleri içe aktar
Sınıflara, işlevlere ve özelliklere ilişkin içe aktarma ifadeleri, tek bir listede birlikte gruplandırılır ve ASCII olarak sıralanır.
Joker karakter içe aktarmalarına (herhangi bir türde) izin verilmez.
Paket ifadesine benzer şekilde, içe aktarma ifadeleri de bir sütun sınırına tabi değildir ve hiçbir zaman satıra sarmalanmaz.
Üst düzey beyanlar
Bir .kt
dosyası, üst düzeyde bir veya daha fazla tür, işlev, özellik ya da tür takma adı tanımlayabilir.
Bir dosyanın içeriği tek bir temaya odaklanmalıdır. Buna örnek olarak tek bir herkese açık tür veya birden fazla alıcı türünde aynı işlemi gerçekleştiren bir dizi uzantı işlevi verilebilir. İlgili olmayan bildirimler kendi dosyalarına ayrılmalıdır ve tek bir dosya içindeki herkese açık bildirimler en aza indirilmelidir.
Dosya içeriklerinin sayısı veya sırası üzerinde açık bir kısıtlama bulunmaz.
Kaynak dosyalar genellikle yukarıdan aşağıya doğru okunur. Yani, sıralama, genel olarak, daha yukarıdaki beyanların, daha aşağıda bulunanların anlaşılmasına yardımcı olacağını yansıtır. Farklı dosyalar, içeriklerini farklı şekilde sıralamayı tercih edebilir. Benzer şekilde, bir dosya 100 özellik, başka bir 10 işlev ve bir başkası da tek bir sınıf içerebilir.
Önemli olan, her dosyanın bazı mantıksal sıralar kullanmasıdır. Mantıksal sıralama kullanılırsa bunu ana yardımcısı açıklayabilir. Örneğin, yeni işlevler yalnızca dosyanın sonuna alışkanlık olarak eklenmiyor, çünkü bu, mantıksal bir sıralama olmayan "eklenme tarihine göre kronolojik" sıralamaya yol açacaktır.
Sınıf üyesi sıralama
Bir sınıf içindeki üyelerin sırası, üst düzey bildirimlerle aynı kurallara uyar.
Biçimlendirme
Diş telleri
Birden fazla else
dalı bulunmayan ve tek bir satıra sığan when
dalları ve if
ifadeleri için küme parantezi gerekli değildir.
if (string.isEmpty()) return val result = if (string.isEmpty()) DEFAULT_VALUE else string when (value) { 0 -> return // … }
Gövde boş olsa veya yalnızca tek bir ifade içerse bile tüm if
, for
, when
dalı, do
ve while
ifadeleri ve ifadeleri için parantez kullanılması gerekir.
if (string.isEmpty()) return // WRONG! if (string.isEmpty()) { return // Okay } if (string.isEmpty()) return // WRONG else doLotsOfProcessingOn(string, otherParametersHere) if (string.isEmpty()) { return // Okay } else { doLotsOfProcessingOn(string, otherParametersHere) }
Boş olmayan bloklar
Dişli ayraçlar, boş olmayan bloklar ve blok benzeri yapılar için Kernighan ve Ritchie stilini ("Mısır parantezleri") izler:
- Açılış küme ayracından önce satır sonu yok.
- Açılış ayraçlarından sonra satır sonu.
- Kapanış parantezinden önce satır sonu.
- Kapanış parantezinden sonra satır sonu. Yalnızca bu küme parantezi bir ifadeyi sona erdirirse ya da işlevin, kurucunun veya adlandırılmış sınıfın gövdesini sonlandırırsa.
Örneğin, süslü ayraçtan sonra
else
veya virgül gelirse satır arası yok.
return Runnable { while (condition()) { foo() } } return object : MyClass() { override fun foo() { if (condition()) { try { something() } catch (e: ProblemException) { recover() } } else if (otherCondition()) { somethingElse() } else { lastThing() } } }
Aşağıda enum sınıfları için birkaç istisna verilmiştir.
Boş bloklar
Boş blok veya blok benzeri yapı K&R stilinde olmalıdır.
try { doSomething() } catch (e: Exception) {} // WRONG!
try { doSomething() } catch (e: Exception) { } // Okay
İfadeler
İfade olarak kullanılan bir if/else
koşulu, yalnızca ifadenin tamamı bir satıra sığıyorsa süslü ayraçları atlayabilir.
val value = if (string.isEmpty()) 0 else 1 // Okay
val value = if (string.isEmpty()) // WRONG! 0 else 1
val value = if (string.isEmpty()) { // Okay 0 } else { 1 }
Girinti
Yeni bir blok veya blok benzeri bir yapı açıldığında, girinti dört boşluk artar. Blok sona erdiğinde, girinti önceki girinti düzeyine geri döner. Girinti düzeyi, blok boyunca hem kod hem de yorumlar için geçerlidir.
Her satıra bir ifade
Her ifadenin ardından bir satır sonu gelir. Noktalı virgül kullanılmaz.
Satır kaydırma
Kodun sütun sınırı 100 karakterdir. Aşağıda belirtilen durumlar dışında, bu sınırı aşacak tüm satırlar aşağıda açıklandığı gibi satır sarmalanmalıdır.
İstisnalar:
- Sütun sınırına uyulmasının mümkün olmadığı satırlar (örneğin, KDoc'taki uzun bir URL)
package
veimport
ekstreleri- Bir yorumda kesilip kabuğa yapıştırılabilen komut satırları
Nerelerde kırılır?
Satır sarmalamanın ana yönergesi şudur: Daha yüksek bir söz dizimi seviyesinde bölmeyi tercih etmek. Ayrıca:
- Bir satır, bir operatör veya infix işlevi adında kesildiğinde bu ara, operatör veya infix işlevi adından sonra gelir.
- Aşağıdaki "operatör benzeri" simgelerde bir çizgi kesildiğinde ara, simgeden önce gelir:
- Nokta ayırıcı (
.
,?.
). - Bir üye referansının iki nokta işareti (
::
).
- Nokta ayırıcı (
- Yöntem veya kurucu adı, kendisinden sonra gelen açık paranteze (
(
) ekli kalır. - Virgül (
,
), önündeki jetona ekli kalır. - Lambda oku (
->
), kendisinden önce gelen bağımsız değişken listesine ekli kalır.
İşlevler
İşlev imzası tek bir satıra sığmadığında her parametre bildirimini kendi satırına bölün. Bu biçimde tanımlanan parametreler tek bir girinti (+4) kullanmalıdır. Kapanış parantezi ()
) ve dönüş türü, ek girinti olmadan kendi satırına yerleştirilir.
fun <T> Iterable<T>.joinToString( separator: CharSequence = ", ", prefix: CharSequence = "", postfix: CharSequence = "" ): String { // … }
İfade işlevleri
Bir işlev yalnızca tek bir ifade içerdiğinde ifade işlevi olarak temsil edilebilir.
override fun toString(): String { return "Hey" }
override fun toString(): String = "Hey"
Özellikler
Bir özellik başlatıcısı tek bir satıra sığmadığında, eşittir işaretinden (=
) sonra ara verin ve bir girinti kullanın.
private val defaultCharset: Charset? = EncodingRegistry.getInstance().getDefaultCharsetForPropertiesFiles(file)
get
ve/veya set
işlevi tanımlayan özellikler, her birini normal girintiyle (+4) kendi satırına yerleştirmelidir. Bunları, aynı kuralları kullanarak
işlevlerle biçimlendirin.
var directory: File? = null set(value) { // … }Salt okunur özellikler, tek bir satıra sığan daha kısa bir söz dizimi kullanabilir.
val defaultExtension: String get() = "kt"
Boşluk
Sektör
Tek bir boş satır görünür:
- Sınıfın ardışık üyeleri arasında: mülkler, kurucular, işlevler, iç içe yerleştirilmiş sınıflar vb.
- İstisna: İki ardışık özellik arasında boş bir satır olması (aralarında başka bir kod olmaması) isteğe bağlıdır. Bu tür boş satırlar, özelliklerin mantıksal gruplamalarını oluşturmak ve varsa, özellikleri destek mülkleriyle ilişkilendirmek için gerektiğinde kullanılır.
- İstisna: Enum sabitleri arasındaki boş satırlar aşağıda ele alınmıştır.
- Kodu mantıksal alt bölümler halinde düzenlemek için gerektiğinde ifadeler arasında.
- İsteğe bağlı olarak bir işlevin ilk ifadeden önce, bir sınıfın ilk üyesinden önce veya bir sınıfın son üyesinden sonra (ne teşvik edilir ne de teşvik edilmez).
- Bu belgenin diğer bölümlerinin gerektirdiği şekilde ( Yapı bölümü gibi).
Art arda birden fazla boş satıra izin verilir, ancak bunlar teşvik edilmez veya hiçbir zaman zorunlu tutulmaz.
Yatay
Dil veya diğer stil kurallarının gerektirdiği durumlarda, harfler, yorumlar ve KDoc'un dışında tek bir ASCII alanı yalnızca aşağıdaki yerlerde görünür:
-
if
,for
veyacatch
gibi ayrılmış kelimeleri bu satırda izleyen açık parantezden ((
) ayırma.// WRONG! for(i in 0..1) { }
// Okay for (i in 0..1) { }
else
veyacatch
gibi ayrılmış kelimeleri bu satırda başındaki kapanış parantezinden (}
) ayırma.// WRONG! }else { }
// Okay } else { }
-
Açık küme parantezinden (
{
) önce.// WRONG! if (list.isEmpty()){ }
// Okay if (list.isEmpty()) { }
-
Herhangi bir ikili operatörün her iki tarafında da bulunur.
// WRONG! val two = 1+1
// Okay val two = 1 + 1
Bu durum, aşağıdaki "operatör benzeri" simgeler için de geçerlidir:- lambda ifadesindeki (
->
) ok işaretini kaldırın.// WRONG! ints.map { value->value.toString() }
// Okay ints.map { value -> value.toString() }
-
bir üye referansının iki adet iki nokta üst üste işareti (
::
).// WRONG! val toString = Any :: toString
// Okay val toString = Any::toString
-
nokta ayırıcıyı (
.
) kullanın.// WRONG it . toString()
// Okay it.toString()
-
aralık operatörü (
..
).// WRONG for (i in 1 .. 4) { print(i) }
// Okay for (i in 1..4) { print(i) }
- lambda ifadesindeki (
-
İki nokta üst üste işareti (
:
) yalnızca temel sınıf veya arayüzleri belirtmek için bir sınıf bildiriminde kullanıldığında ya da genel kısıtlamalar içinwhere
ifadesinde kullanıldığında.// WRONG! class Foo: Runnable
// Okay class Foo : Runnable
// WRONG fun <T: Comparable> max(a: T, b: T)
// Okay fun <T : Comparable> max(a: T, b: T)
// WRONG fun <T> max(a: T, b: T) where T: Comparable<T>
// Okay fun <T> max(a: T, b: T) where T : Comparable<T>
-
Virgül (
,
) veya iki nokta üst üste işaretinden (:
) sonra.// WRONG! val oneAndTwo = listOf(1,2)
// Okay val oneAndTwo = listOf(1, 2)
// WRONG! class Foo :Runnable
// Okay class Foo : Runnable
-
Satır sonu yorumunu başlatan çift eğik çizginin (
//
) her iki tarafında da. Burada birden fazla boşluk kullanılabilir, ancak zorunlu değildir.// WRONG! var debugging = false//disabled by default
// Okay var debugging = false // disabled by default
Bu kural hiçbir zaman bir satırın başında veya sonunda ek boşluk gerektirmek veya vermekten ibaret olarak yorumlanmaz; yalnızca iç alanı ele alır.
Belirli yapılar
Enum sınıfları
İşlevi olmayan ve sabit değerlerinde belge içermeyen bir enum, isteğe bağlı olarak tek satır olarak biçimlendirilebilir.
enum class Answer { YES, NO, MAYBE }
Bir enumdaki sabit değerler ayrı satırlara yerleştirildiğinde, gövde tanımladıkları durumlar dışında bunların arasında boş bir satır gerekmez.
enum class Answer { YES, NO, MAYBE { override fun toString() = """¯\_(ツ)_/¯""" } }
Enum sınıfları sınıf olduğundan, biçimlendirme sınıflarına yönelik diğer tüm kurallar geçerlidir.
Ek açıklamalar
Üye veya tür ek açıklamaları, ek açıklamalı yapıdan hemen önce ayrı satırlara yerleştirilir.
@Retention(SOURCE) @Target(FUNCTION, PROPERTY_SETTER, FIELD) annotation class Global
Bağımsız değişken içermeyen ek açıklamalar tek bir satıra yerleştirilebilir.
@JvmField @Volatile var disposable: Disposable? = null
Bağımsız değişken içermeyen tek bir ek açıklama bulunduğunda bu ek açıklama, bildirimle aynı satıra yerleştirilebilir.
@Volatile var disposable: Disposable? = null @Test fun selectAll() { // … }
@[...]
söz dizimi yalnızca açık bir kullanım sitesi hedefiyle ve sadece tek bir satırda bağımsız değişken içermeyen 2 veya daha fazla ek açıklamayı birleştirmek için kullanılabilir.
@field:[JvmStatic Volatile] var disposable: Disposable? = null
Dolaylı iade/mülk türleri
Bir ifade işlevi gövdesi veya özellik başlatıcısı skaler bir değerse ya da döndürme türü gövdeden net bir şekilde çıkarılabiliyorsa bu değer çıkarılabilir.
override fun toString(): String = "Hey" // becomes override fun toString() = "Hey"
private val ICON: Icon = IconLoader.getIcon("/icons/kotlin.png") // becomes private val ICON = IconLoader.getIcon("/icons/kotlin.png")
Kitaplık yazarken açık tür bildirimini, genel API'nin parçası olduğunda saklayın.
Adlandırma
Tanımlayıcılar yalnızca ASCII harfleri ve rakamların yanı sıra aşağıda belirtilen bazı durumlarda alt çizgi kullanır. Dolayısıyla, her geçerli tanımlayıcı adı \w+
normal ifadesiyle eşleştirilir.
name_
, mName
, s_name
ve kName
örneklerinde görülenler gibi özel önekler veya sonekler, yedekleme özellikleri durumu dışında kullanılmaz (bkz. Yedekleme özellikleri).
Paket Adları
Paket adlarının tümü küçük harfle yazılır ve ardışık kelimeler birbirine eklenir (alt çizgi olmadan).
// Okay package com.example.deepspace // WRONG! package com.example.deepSpace // WRONG! package com.example.deep_space
Adları yazın
Sınıf adları PascalCase ile yazılır ve genellikle isimlerden veya isim kelime öbeklerinden oluşur. Örneğin, Character
veya ImmutableList
. Arayüz adları, ad veya isim kelime öbekleri (örneğin, List
) olabilir ancak bazen sıfat veya sıfat ifadelerinden de oluşabilir (örneğin Readable
).
Test sınıfları, test ettikleri sınıfın adından başlanarak Test
ile biter. Örneğin, HashTest
veya
HashIntegrationTest
.
İşlev adları
İşlev adları büyük-küçük harf kullanılarak yazılır ve genellikle fiil veya fiil kelime öbeklerinden oluşur. Örneğin, sendMessage
veya stop
.
Adın mantıksal bileşenlerini ayırmak için test işlevi adlarında alt çizgi kullanılmasına izin verilir.
@Test fun pop_emptyStack() { // … }
Unit
değerini döndüren, @Composable
ile ek açıklama eklenen işlevler PascalCased'dir ve türler gibi isim olarak adlandırılır.
@Composable fun NameTag(name: String) { // … }
İşlev adları boşluk içermemelidir çünkü bu özellik her platformda desteklenmez (özellikle Android'de tam olarak desteklenmez).
// WRONG! fun `test every possible case`() {} // OK fun testEveryPossibleCase() {}
Sabit adlar
Sabit adlarda UPPER_SNAKE_CASE kullanılır: Tüm kelimeler büyük harflerden oluşur ve kelimeler alt çizgiyle ayrılır. Peki sabit değer nedir tam olarak?
Sabitler, özel get
işlevi olmayan, içerikleri son derece sabit olan ve işlevlerinin algılanabilir yan etkisi olmayan val
özellikleridir. Sabit türler ve sabit türlerden oluşan sabit koleksiyonların yanı sıra const
olarak işaretlenen skaler ve dizeleri de içerir. Bir örneğin gözlemlenebilir durumundan herhangi biri değişebiliyorsa bu değer sabit değildir. Nesneyi asla
değiştirmemek yeterli değildir.
const val NUMBER = 5 val NAMES = listOf("Alice", "Bob") val AGES = mapOf("Alice" to 35, "Bob" to 32) val COMMA_JOINER = Joiner.on(',') // Joiner is immutable val EMPTY_ARRAY = arrayOf()
Bu adlar genellikle isimlerden veya isim kelime öbeklerinden oluşur.
Sabit değerler yalnızca bir object
içinde veya üst düzey bildirim olarak tanımlanabilir. Aksi takdirde sabit değer gereksinimini karşılayan ancak class
içinde tanımlanan değerler sabit olmayan bir ad kullanmalıdır.
Skaler değerler olan sabit değerler, const
değiştiriciyi kullanmalıdır.
Sabit olmayan adlar
Sabit olmayan adlar büyük/küçük harf durumunda yazılır. Bunlar örnek özellikleri, yerel özellikler ve parametre adları için geçerlidir.
val variable = "var" val nonConstScalar = "non-const" val mutableCollection: MutableSet= HashSet() val mutableElements = listOf(mutableInstance) val mutableValues = mapOf("Alice" to mutableInstance, "Bob" to mutableInstance2) val logger = Logger.getLogger(MyClass::class.java.name) val nonEmptyArray = arrayOf("these", "can", "change")
Bu adlar genellikle isimlerden veya isim kelime öbeklerinden oluşur.
Özellikleri destekleme
Yedekleme özelliği gerektiğinde, özelliğin adı alt çizgiyle öne çıkarılmadıkça gerçek mülkün adıyla tam olarak eşleşmelidir.
private var _table: Map? = null val table: Map get() { if (_table == null) { _table = HashMap() } return _table ?: throw AssertionError() }
Değişken adları yazın
Her tür değişkeni iki stilden birinde adlandırılır:
- İsteğe bağlı olarak tek bir büyük harf ve ardından tek bir sayı gelmelidir (ör.
E
,T
,X
,T2
) - Sınıflar için kullanılan biçimde bir ad ve büyük harfle başlayan
T
(ör.RequestT
,FooBarT
)
Deve kılıfı
Bazen kısaltmalar ya da "IPv6" veya "iOS" gibi alışılmadık yapılar olması gibi İngilizce bir ifadeyi deveye dönüştürmenin birden fazla makul yolu vardır. Öngörülebilirliği iyileştirmek için aşağıdaki şemayı kullanın.
Adın düz yazı biçimiyle başlayarak:
- Kelime öbeğini düz ASCII'ye dönüştürün ve kesme işaretlerini kaldırın. Örneğin, "Müller algoritması" "Müller algoritması" haline gelebilir.
- Bu sonucu kelimelere bölün, boşluklara ve kalan noktalama işaretlerine (genellikle kısa çizgi) bölün. Önerilen: Yaygın olarak kullanılan geleneksel deve ağacı görünümüne sahip bir kelime varsa bunu bileşenlerine (ör. "AdWords", "reklam kelimeleri" haline gelir.") "iOS" gibi bir kelimenin aslında büyük/küçük harf kullanımı için uygun olmadığını, her kurala uygun olmadığını ve dolayısıyla bu önerinin geçerli olmadığını unutmayın.
- Şimdi her şeyi (kısaltmalar dahil) küçük harfle yazın ve aşağıdakilerden birini yapın:
- Pascal değerinin büyük olması için her kelimenin ilk karakterini büyük harfle yazın.
- Deveye dönüşen ilk kelime hariç, her kelimenin ilk karakterini büyük harfle yazın.
- Son olarak, tüm kelimeleri tek bir tanımlayıcıda birleştirin.
Orijinal kelimelerin büyük/küçük harf kullanımının neredeyse tamamen dikkate alınmadığını unutmayın.
Düzey formu | Doğru | Yanlış |
---|---|---|
"XML Http İsteği" | XmlHttpRequest |
XMLHTTPRequest |
"yeni müşteri kimliği" | newCustomerId |
newCustomerID |
"iç kronometre" | innerStopwatch |
innerStopWatch |
"iOS'te IPv6'yı destekler" | supportsIpv6OnIos |
supportsIPv6OnIOS |
"YouTube içeri aktarma aracı" | YouTubeImporter |
YoutubeImporter * |
(* Kabul edilebilir ancak önerilmez.)
Belgeler
Biçimlendirme
KDoc bloklarının temel biçimlendirmesi aşağıdaki örnekte gösterilmiştir:
/** * Multiple lines of KDoc text are written here, * wrapped normally… */ fun method(arg: String) { // … }
...veya bu tek satırlık örnekte:
/** An especially short bit of KDoc. */
Temel biçim her zaman kabul edilir. KDoc bloğunun tamamı (yorum işaretçileri dahil) tek bir satıra sığdığında tek satırlı biçim değiştirilebilir. Bunun yalnızca @return
gibi engelleme etiketi olmadığında geçerli olduğunu unutmayın.
Paragraflar
Boş bir satır, yani yalnızca başında hizalı yıldız işaretini (*
) içeren bir satır, paragraflar arasında ve varsa blok etiketleri grubundan önce görünür.
Etiketleri engelle
Kullanılan standart "engelleme etiketleri" @constructor
, @receiver
, @param
, @property
, @return
,
@throws
, @see
sırasında görünür ve bunlar hiçbir zaman boş bir açıklamayla görünmez.
Bir blok etiketi tek bir satıra sığmazsa devam satırları @
konumundan 4 boşluk girintili olarak yapılır.
Özet bölümü
Her KDoc bloğu, kısa bir özet parçasıyla başlar. Bu parça çok önemlidir: Sınıf ve yöntem dizinleri gibi belirli bağlamlarda görünen metnin tek bölümüdür.
Bu, tam bir cümle değil, parça anlamına gelir. Bir isim ifadesi veya fiil ifadesidir.
"A `Foo` is a...
" veya "This method returns...
" ile başlamaz ve "Save the record.
" gibi tam bir zorunlu cümlesi oluşturması da gerekmez. Bununla birlikte, parçada büyük harfle ve tam bir cümleymiş gibi noktalama işareti kullanılır.
Kullanım
KDoc, en azından aşağıda belirtilen birkaç istisna dışında her public
türü ve bu tür bir türdeki her public
veya protected
üyesi için mevcuttur.
İstisna: Kendini açıklayan işlevler
KDoc, getFoo
gibi "basit, bariz" işlevler ve foo
gibi özellikler için isteğe bağlıdır. Bu durumlarda, "foo'yu döndürür"den başka bir şey söylenmeye değmez.
Tipik bir okuyucunun bilmesi gereken alakalı bilgilerin verilmemesi için bu istisnadan alıntı yapmak uygun değildir. Örneğin, tipik bir okuyucunun "standart ad" teriminin ne anlama geldiği hakkında hiçbir fikri yoksa getCanonicalName
adlı işlev veya canonicalName
adlı özellik için dokümanlarını (sadece /** Returns the canonical name. */
denmesini gerekçeyle) ihmal etmeyin.
İstisna: geçersiz kılmalar
KDoc, bir üst tür yöntemini geçersiz kılan yöntemde her zaman mevcut değildir.