Bu belge, Kotlin Programlama Dilinde kaynak koda yönelik Google'ın Android kodlama standartlarının tam tanımını sağlamaktadır. Kotlin kaynak dosyası, yalnızca buradaki kurallara uygun olduğu takdirde Google Android Stili'nde olarak tanımlanır.
Diğer programlama stili kılavuzları gibi, ele alınan konular yalnızca biçimlendirmeyle ilgili estetik konuları 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 kısa kurallara odaklanmaktadır ve (hem gerçek kişiler hem de araçlar tarafından) açıkça uygulanabilir olmayan tavsiyelerde bulunmaktan 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, kaynak dosyada birden çok üst düzey bildirim varsa dosyanın içeriğini açıklayan bir ad seçin, PascalCase'i uygulayın (dosya adı çoğulsa CamelCase kabul edilebilir) 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ı dizisinden ayrı olarak, kaynak dosyanın herhangi bir yerinde görünen tek boşluk karakteri ASCII yatay boşluk karakteri (0x20)'dir. Bunun anlamı şudur:
- Dize ve karakter değişmez değerlerindeki diğer tüm boşluk karakterleri kod dışı bırakılır.
- Girinti için sekme karakterleri kullanılmaz.
Özel kaçış dizileri
Özel bir kaçış dizisine sahip herhangi bir karakter için (\b
, \n
, \r
, \t
, \'
, \"
, \\
ve \$
) karşılık gelen Unicode (ör. \u000a
) kod dışı bırakın.
ASCII olmayan karakterler
Geri kalan ASCII olmayan karakterler için ya gerçek Unicode karakteri (ör. ∞
) veya eşdeğer bir Unicode çıkışı (ör. \u221e
) kullanılır.
Yapacağınız seçim, yalnızca hangi yöntemin kodu okumayı ve anlamayı daha kolay hale getirdiğine bağlıdır.
Unicode çıkışları, herhangi bir konumdaki 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 yazmasa bile son derece nettir. |
val unitAbbrev = "\u03bcs" // μs |
Kötü: Yazdırılabilir bir karakter kullanarak kaçış karakteri kullanmak için hiçbir sebep yoktur. |
val unitAbbrev = "\u03bcs" |
Kötü: Okuyucunun bunun ne olduğuna dair hiçbir fikri yok. |
return "\ufeff" + content |
İyi: Yazdırılamayan karakterler için çıkış 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
- İfadeleri içe aktarın
- Üst düzey beyanlar
Bu bölümlerin her birini tam olarak bir boş satır ayırır.
Telif Hakkı / Lisans
Dosyada bir telif hakkı veya lisans başlığı varsa üstbilgi, çok satırlı yorumun hemen en üstüne yerleştirilmelidir.
/* * Copyright 2017 Google, Inc. * * ... */
KDoc stili veya tek satırlık stilde yorum kullanmayın.
/** * Copyright 2017 Google, Inc. * * ... */
// Copyright 2017 Google, Inc. // // ...
Dosya düzeyinde ek açıklamalar
"file" use-site target içeren notlar, 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.
İfadeleri içe aktarın
Sınıflara, işlevlere ve özelliklere ilişkin içe aktarma ifadeleri tek bir liste halinde gruplandırılır ve ASCII sıralanmış olarak sıralanır.
Hiçbir türde joker karakter içe aktarmaya izin verilmez.
Paket ifadesine benzer şekilde, içe aktarma ifadeleri bir sütun sınırına tabi değildir ve hiçbir zaman satırdan sarmalanmaz.
Üst düzey beyanlar
Bir .kt
dosyası, üst düzeyde bir veya daha fazla tür, işlev, özellik veya tür takma adı bildirebilir.
Bir dosyanın içeriği tek bir temaya odaklanmalıdır. Birden fazla alıcı türünde aynı işlemi gerçekleştiren tek bir herkese açık tür veya uzantı işlevleri grubu buna örnek olarak gösterilebilir. İlgili olmayan bildirimler kendi dosyalarına ayrılmalıdır ve tek bir dosya içindeki herkese açık bildirimler en aza indirilmelidir.
Dosyalardaki içeriklerin sayısı veya sırası üzerinde açık bir kısıtlama uygulanmaz.
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ıtmalıdır. Farklı dosyalar, içeriklerini farklı şekilde sıralamayı tercih edebilir. Benzer şekilde, bir dosya 100 özellik, başka bir 10 işlev ve başka bir dosya da tek bir sınıf içerebilir.
Önemli olan, her dosyanın bir mantıksal sıra kullanmasıdır. İstendiğinde dosyanın sorumlusu bunu açıklayabilir. Örneğin, yeni işlevler sadece dosyanın sonuna düzenli olarak eklenmez, çünkü bu durumda "eklenme tarihine göre kronolojik" bir sıralama elde edilir, bu da mantıksal bir sıralama değildir.
Sınıf üyesi sıralaması
Bir sınıftaki üyelerin sırası, üst düzey bildirimlerle aynı kurallara uyar.
Biçimlendirme
Diş telleri
En fazla bir else
dalı olan ve tek bir satıra sığan when
dalları ve if
ifadeleri için süslü ayraçlar 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 parantezler 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ış küme ayracından sonra satır sonu.
- Kapanış parantezinden önce satır sonu.
- Kapanış parantezinden sonra satır sonu. Yalnızca bu parantez bir ifadeyi sonlandırıyorsa veya bir işlevin, kurucunun veya adlandırılmış sınıfının gövdesini sonlandırıyorsa.
Örneğin, başında
else
veya virgül varsa küme parantezinden sonra no satır sonu olmaz.
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ş bir 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 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, bloktaki 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ılmamalıdır.
Satır kaydırma
Kodun sütun sınırı 100 karakterdir. Aşağıda belirtilenler dışında, bu sınırı aşacak tüm satırlar aşağıda açıklandığı gibi satırla sarmalanmalıdır.
İstisnalar:
- Sütun sınırına uymanın mümkün olmadığı satırlar (örneğin, KDoc'taki uzun bir URL)
package
veimport
ekstreleri- Yorumdaki, kesilip kabuğa yapıştırılabilen komut satırları
Nerede mola verilir?
Satır sarmalamanın ana yönergesi şudur: Daha yüksek bir söz dizimsel düzeyde bölmeyi tercih etmek. Ayrıca:
- Bir operatör veya infix işlev adında bir satır kırıldığında ara, operatör veya infix işlev adından sonra gelir.
- Aşağıdaki "operatör benzeri" simgelerde bir çizgi kırıldığında, sembolden önce ara gelir:
- Nokta ayırıcı (
.
,?.
). - Üye referansının iki nokta üst üste işareti (
::
).
- Nokta ayırıcı (
- Yöntem veya kurucu adı, kendisinden sonra gelen açık paranteze (
(
) ekli kalır. - Virgül (
,
), kendisinden önce gelen jetona ekli kalır. - Lambda oku (
->
), kendisinden önce gelen bağımsız değişken listesine ekli kalır.
Fonksiyonlar
Bir iş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"
Kod
Bir özellik başlatıcı 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 mülkler, her birini normal bir 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
Dikey
Tek bir boş satır görünür:
- Sınıfın ardışık üyeleri arasında: özellikler, kurucular, işlevler, iç içe yerleştirilmiş sınıflar.
- İstisna: Birbirini izleyen iki özellik arasında boş bir satır olması (aralarında başka kod olmaması) isteğe bağlıdır. Bu tür boş satırlar, mantıksal mülk grupları oluşturmak ve varsa özellikleri, destek mülkleriyle ilişkilendirmek için gerektiğinde kullanılır.
- İstisna: Sıralama 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 ifadeler arasında, gerektiğinde.
- İsteğe bağlı olarak bir işlevdeki 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 ( Yapı bölümü gibi) gerektirdiği şekilde.
Art arda birden fazla boş satıra izin verilir, ancak teşvik edilmez veya hiçbir zaman zorunlu değildir.
Yatay
Dil veya diğer stil kurallarının gerektirdiği durumların ötesinde, hazır değerler, yorumlar ve KDoc 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 bir parantezden ((
) ayırmak.// WRONG! for(i in 0..1) { }
// Okay for (i in 0..1) { }
else
veyacatch
gibi ayrılmış bir kelimeyi, bu satırda kendisinden önce gelen bir kapanış parantezinden (}
) ayırma.// WRONG! }else { }
// Okay } else { }
-
Açık küme parantezinden (
{
) önce.// WRONG! if (list.isEmpty()){ }
// Okay if (list.isEmpty()) { }
-
İkili operatörde her iki taraf için de geçerlidir.
// WRONG! val two = 1+1
// Okay val two = 1 + 1
Bu kural, aşağıdaki "operatör benzeri" simgeler için de geçerlidir:- lambda ifadesindeki ok (
->
).// WRONG! ints.map { value->value.toString() }
// Okay ints.map { value -> value.toString() }
-
üye referansının iki nokta üst üste işaretini (
::
).// WRONG! val toString = Any :: toString
// Okay val toString = Any::toString
-
nokta ayırıcısı (
.
) kullanılır.// 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 ok (
-
İki nokta üst üste işaretinden (
:
) önce, 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 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 yorumu başlatan çift eğik çizginin (
//
) her iki tarafında. 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 gerektirecek veya buna izin verilmediği şeklinde yorumlanmaz; yalnızca iç mekanlara yöneliktir.
Belirli yapılar
Sıralama sınıfları
İşlevi ve sabit değerlerinde belgesi olmayan bir enum, isteğe bağlı olarak tek satır olarak biçimlendirilebilir.
enum class Answer { YES, NO, MAYBE }
Bir numaralandırmadaki sabit değerler ayrı satırlara yerleştirildiğinde, bir gövde tanımladıkları durumlar dışında bunlar arasında boş bir satıra gerek yoktur.
enum class Answer { YES, NO, MAYBE { override fun toString() = """¯\_(ツ)_/¯""" } }
Sıralama sınıfları sınıf olduğundan diğer tüm biçimlendirme sınıfları 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 belirli bir kullanım sitesi hedefiyle ve yalnızca 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
Örtülü iade/mülk türleri
Bir ifade işlevinin gövdesi veya özellik başlatıcısı skaler bir değerse ya da döndürme türü, gövdeden açıkça anlaşılabilirse atlanabilir.
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")
Bir kitaplık yazarken, genel API'nin parçası olduğunda açık tür bildirimini saklayın.
Adlandırma
Tanımlayıcılar yalnızca ASCII harfleri ile rakamları ve aşağıda belirtilen birkaç durumda 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 ön ekler veya sonekler, yedekleme özellikleri dışında kullanılmaz (Destek özellikleri bölümüne bakın).
Paket Adları
Paket adlarının tümü küçük harfle yazılır ve ardışık kelimeler birbirine bağlanır (alt çizgi olmadan).
// Okay package com.example.deepspace // WRONG! package com.example.deepSpace // WRONG! package com.example.deep_space
Tür adları
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ı, isimler veya isim ifadeleri (ör. List
) da 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ıyla başlar ve 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
.
Alt çizgi işaretlerinin, adın mantıksal bileşenlerini ayırmak için test işlevi adlarında görünmesine izin verilir.
@Test fun pop_emptyStack() { // … }
Ek açıklaması @Composable
olan ve Unit
değeri döndüren işlevler PascalCased'dır ve türler gibi isim olarak adlandırılır.
@Composable fun NameTag(name: String) { // … }
İşlev adları boşluk içermemelidir, çünkü Android'de bu özellik tam olarak desteklenmez.
// WRONG! fun `test every possible case`() {} // OK fun testEveryPossibleCase() {}
Sabit adlar
Sabit adlarda UPPER_SNAKE_CASE UPPER_SNAKE_CASE kullanılır: Tüm kelimeler büyük harflerden oluşur ve kelimeler alt çizgiyle ayrılır. Peki, sabit nedir tam olarak?
Sabitler, özel bir get
işlevi olmayan, içerikleri son derece sabit olan ve işlevlerinin algılanabilir yan etkileri olmayan val
özellikleridir. Buna sabit türler ve sabit türlerin sabit koleksiyonlarının yanı sıra const
olarak işaretlendiyse skaler ve dize dahildir. Bir örneğin gözlemlenebilir durumu değişebiliyorsa sabit değildir. Sadece nesneyi asla
değiştirmeyi amaçlamak 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 bir bildirim olarak tanımlanabilir. Aksi takdirde sabit değer şartını karşılayan ancak class
içinde tanımlanan değerler sabit olmayan bir ad kullanmalıdır.
Skaler değerler olan sabitler const
değiştiriciyi kullanmalıdır.
Sabit olmayan adlar
Sabit olmayan adlar büyük/küçük harf kullanımıyla 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ı gerçek mülkün adıyla tam olarak eşleşmelidir (öne alt çizgi eklenmesi hariç).
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 bir 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 rakam gelir (ör.
E
,T
,X
,T2
) - Sınıflar için kullanılan biçimde bir ad ve büyük
T
harfi (ör.RequestT
,FooBarT
)
Deve kılıfı
Bazen kısaltmalar veya “IPv6” ya da “iOS” gibi sıra dışı yapılar olması gibi İngilizce bir ifadeyi deve harfine dönüştürmenin birden fazla makul yolu vardır. Tahmin edilebilirliği iyileştirmek için aşağıdaki şemayı kullanın.
Adın düz yazı biçimiyle başlayarak:
- İfadeyi düz ASCII'ye dönüştürün ve kesme işaretlerini kaldırın. Örneğin, “Müller algoritması” “Muellers algoritması” haline gelebilir.
- Bu sonucu kelimelere bölün, boşlukları ve kalan noktalama işaretlerini (genellikle kısa çizgileri) bölün. Önerilen: Herhangi bir kelime yaygın olarak bilinen geleneksel deve harf kullanımına sahipse bunu bileşenlerine ayırın (ör. “AdWords”, “reklam kelimeleri” haline gelir. “iOS” gibi bir kelimenin tek başına büyük/küçük harf kullanımı olmadığını, her kurala uygun olmadığını unutmayın. Dolayısıyla bu öneri geçerli değildir.
- Şimdi her şeyi (kısaltmalar dahil) küçük harfle yazdıktan sonra aşağıdakilerden birini yapın:
- Paskal büyük/küçük harf kullanımı için her kelimenin ilk karakterini büyük harfle yazın.
- Deve ilk harfini içeren 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ı neredeyse tamamen dikkate alınmaz.
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çe aktarma aracı" | YouTubeImporter |
YoutubeImporter * |
(* Kabul edilebilir, ancak önerilmez.)
Dokümanlar
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ığabildiğinde tek satırlı biçim değiştirilebilir. Bunun yalnızca @return
gibi engelleme etiketi olmadığında geçerli olduğunu unutmayın.
Paragraf
Paragraflar arasında ve varsa blok etiketler grubundan önce boş bir satır (yani, başında hizalı yıldız işaretini (*
) içeren bir satır) görünür.
Etiketleri engelle
Kullanılan standart "engelleme etiketleri"nden herhangi biri @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.
Blok etiketi tek bir satıra sığmadığında devam satırları @
konumundan 4 boşluk girintili olarak gösterilir.
Özet parçası
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 metnin görünen tek bölümüdür.
Bu bir parçadır. Bir ad ifadesi veya fiil ifadesidir, tam bir cümle değildir.
"A `Foo` is a...
" veya "This method returns...
" ile başlamaz ve "Save the record.
" gibi tam bir zorunluluk cümlesi oluşturması da gerekmez. Bununla birlikte, parça büyük harfle yazılmış ve tam bir cümleymiş gibi noktalama işaretleriyle gösterilmiştir.
Kullanım
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 KDoc mevcuttur.
İstisna: Kendini açıklayan işlevler
KDoc, getFoo
gibi "basit, bariz" işlevler ve foo
gibi mülkler için isteğe bağlıdır. Bu durumlarda, "foo'yu döndürür" ifadesinden başka bir şey söylenmeye değmez.
Tipik bir okuyucunun bilmesi gereken alakalı bilgilerin verilmemesi için bu istisnaya yer vermek uygun değildir. Örneğin, tipik bir okuyucunun "standart ad" teriminin ne anlama geldiğine dair hiçbir fikri yoksa getCanonicalName
adlı işlev veya canonicalName
adlı özellik ile ilgili dokümanlarını (mantıkıyla yalnızca /** Returns the canonical name. */
şeklinde olmalıdır) atlamayın.
İstisna: geçersiz kılmalar
KDoc, süper tür yöntemini geçersiz kılan bir yöntemde her zaman mevcut değildir.