Bu dokümanda, Google'ın Kotlin Programlama Dili'ndeki kaynak kodu için Android kodlama standartlarının tam tanımı açıklanmaktadır. Bir Kotlin kaynak dosyası, yalnızca buradaki kurallara uyduğu takdirde Google Android Stili'nde olduğu için tanımlanır.
Diğer programlama stil kılavuzlarında olduğu gibi, ele alınan sorunlar sadece biçimlendirmeyle ilgili estetik sorunları değil, aynı zamanda diğer kural türlerini veya kodlama standartlarını da kapsıyor. Ancak bu belge, öncelikle evrensel olarak izlediğimiz katı ve değişmez kurallara odaklanmaktadır ve açıkça uygulanabilir olmayan (insan veya araç tarafından) tavsiyelerde bulunmaktan kaçınır.
Kaynak dosyalar
Tüm kaynak dosyalar UTF-8 olarak kodlanmalıdır.
Adlandırma
Kaynak dosyada yalnızca tek bir üst düzey sınıf varsa dosya adı
büyük/küçük harfe duyarlı ad ile .kt
uzantısını yansıtmalıdır. Aksi halde
Kaynak dosya birden fazla üst düzey bildirim içeriyorsa bir ad seçin
açıklamaya çalışın, PascalCase'ı (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ı dizisinin dışında, ASCII yatay boşluk karakteri (0x20) kaynak dosyada herhangi bir yerde görünen tek boşluk karakteridir. Bu, şu anlama gelir:
- Dize ve karakter değişmez değerlerindeki diğer tüm boşluk karakterleri atlanır.
- Sekme karakterleri girinti için kullanılmaz.
Özel kaçış dizileri
Özel bir kaçış dizisi olan tüm karakterler için
(\b
, \n
, \r
, \t
, \'
, \"
, \\
ve \$
),
ilgili Unicode yerine bu sıranın kullanılması
(ör. \u000a
) kod dışı bırakılır.
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.
Seçim, kodu yapan kişiye bağlıdır
daha kolay okunup anlaşılır.
Herhangi bir konumda yazdırılabilir karakterler için Unicode çıkışlarının kullanılması önerilmez.
dize değişmez değerleri ve yorumları dışında kesinlikle önerilmez.
Örnek | Tartışma |
---|---|
val unitAbbrev = "μs" |
En iyi: Yorum yapılmadan bile son derece nettir. |
val unitAbbrev = "\u03bcs" // μs |
Kötü: Yazdırılabilir bir karakterle çıkış karakterlerini kullanmak için hiçbir neden yoktur. |
val unitAbbrev = "\u03bcs" |
Kötü: Okuyucu, bunun ne olduğu hakkında bir fikri yoktu. |
return "\ufeff" + content |
İyi: Yazdırılamayan karakterler için çıkışlar kullanın ve gerekirse yorum yapın. |
Yapı
.kt
dosyası sırasıyla şu öğelerden oluşur:
- Telif hakkı ve/veya lisans başlığı (isteğe bağlı)
- Dosya düzeyinde ek açıklamalar
- Paket ekstresi
- İfadeleri içe aktar
- Üst düzey bildirimler
Bu bölümlerin her biri, tek bir boş satırla ayrılacaktır.
Telif Hakkı / Lisans
Dosyaya ait olan telif hakkı veya lisans başlığı, çok satırlı bir yorumun en üstüne yerleştirilmelidir.
/* * Copyright 2017 Google, Inc. * * ... */
KDoc stili kullanmayın veya tek satırlık bir yorum yazmak gibidir.
/** * Copyright 2017 Google, Inc. * * ... */
// Copyright 2017 Google, Inc. // // ...
Dosya düzeyinde ek açıklamalar
"Dosya" içeren notlar use-site hedefi etiketleri, herhangi bir başlık yorumu ile paket bildirimi arasına yerleştirilir.
Paket ekstresi
Paket ifadesi, herhangi bir sütun sınırına tabi değildir ve hiçbir zaman satırla sarmalanmaz.
İfadeleri içe aktar
Sınıflara, işlevlere ve özelliklere ilişkin içe aktarma ifadeleri tek bir listede gruplandırılır ve ASCII olarak sıralanır.
Joker karakter içe aktarma işlemlerine (herhangi bir türde) izin verilmez.
Paket ifadesiyle benzer şekilde, içe aktarma ifadeleri sütun sınırı vardır ve hiçbir zaman satır kaydırılmazlar.
Üst düzey bildirimler
.kt
dosyası bir veya daha fazla tür, işlev, özellik ya da tür bildirebilir
takma adlar var.
Dosya içeriği tek bir temaya odaklanmalıdır. Buna örnekler herkese açık tek bir tür veya birden fazla alıcı türünde aynı işlemi yapmanıza olanak tanır. Alakasız beyanlar kendi dosyalarına ve kamuya açık beyanlarına göre tek bir dosyada ayrılmış olarak en aza indirilmelidir.
İçeriklerin sayısı veya sırası üzerinde açık bir kısıtlama uygulanmaz. olabilir.
Kaynak dosyalar genellikle yukarıdan aşağıya doğru okunur. Bu da, üst kısımlardaki beyannameler, bahsi geçen daha iyi anlamanızı sağlar. Farklı dosyalar sipariş edilebilir değişiklik gösterebilir. Benzer şekilde, bir dosyada 100 özellik bulunabilir, 10 işlev daha ve başka bir sınıf daha.
Önemli olan her bir dosyanın bir mantıksal sıralama kullanmasıdır. durumu açıklayabilir. Örneğin, yeni işlevler dosyanın sonuna eklenir. Bu da “kronolojik şeklinde bir sıralamaya ekleyebilirsiniz. Bu, mantıksal bir sıralama değildir.
Sınıf üyeleri sıralaması
Bir sınıftaki üyelerin sırası, üst düzey üyelerle aynı kurallara uyar beyanları.
Biçimlendirme
Diş telleri
when
dallar ve if
ifadeler için küme ayraçları gerekli değildir
birden fazla else
dalı olmayan ve tek bir satıra sığan.
if (string.isEmpty()) return val result = if (string.isEmpty()) DEFAULT_VALUE else string when (value) { 0 -> return // … }
Bunun dışında herhangi bir if
, for
, when
dalı, do
,
Gövde boş olduğunda veya yalnızca şunu içerse bile, while
ifadeleri ve ifadeleri
düşünebilirsiniz.
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
Semboller için Kernighan ve Ritchie tarzı ("Mısır parantezleri") kullanılır boş olmayan bloklar ve blok benzeri yapılar:
- Açılış parantezinden önce satır sonu yok.
- Açılış parantezinden sonra satır sonu.
- Kapanış ayracından önce satır sonu.
- Kapanış ayracından sonra satır sonu, yalnızca bu küme ayracı sona ererse
ifadesi veya bir işlevin, kurucunun ya da adlandırılmış sınıfın gövdesini sonlandırır.
Örneğin, arkasından şöyle satır geliyorsa küme parantezinden sonra satır sonu yok:
else
veya virgül.
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() } } }
Proje yöneticilerinin enum sınıfları aşağıda verilmiştir.
Boş bloklar
Boş blok veya blok benzeri bir yapı K&R tarzında 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
küme ayraçlarını yalnızca tüm ifade bir satıra sığıyorsa atlayın.
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 yapı her açıldığında girinti dört boşluk artar. Blok sona erdiğinde girinti önceki girinti düzeyine 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 sarmalama
Kodun 100 karakterlik bir sütun sınırı vardır. Aşağıda belirtilenler dışında, bu sınırı aşacak tüm satırlar aşağıda açıklandığı gibi satıra 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- Bir yorumdaki kesilip kabuğa yapıştırılabilecek komut satırları
Nerelerde popülerlik yapılabilir?
Satır sarmalamanın ana yönergesi: daha yüksek söz dizimsel düzeyde kesmeyi tercih edin. Ayrıca:
- İşleç veya infix fonksiyon adında bir satır kırıldığında, operatör veya infix fonksiyon adından sonra gelir.
- Aşağıdaki "operatör benzeri" sembollerde bir çizgi kesildiğinde,
sembolden önce gelir:
- Nokta ayırıcı (
.
,?.
). - Üye referansındaki iki iki nokta işareti (
::
).
- Nokta ayırıcı (
- Bir yöntem veya kurucu adı, aynı işleve sahip açık paranteze (
(
) ekli kalır o takip eder. - Virgül (
,
), kendisinden önce gelen jetona ekli kalır. - Lambda oku (
->
), kendisinden önceki bağımsız değişken listesine ekli kalıyor.
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 parametrelerde tek bir girinti (+4) kullanılmalı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 fonksiyon tek bir ifade içerdiğinde ifade işlevine sahip olması gerekir.
override fun toString(): String { return "Hey" }
override fun toString(): String = "Hey"
Özellikler
Özellik başlatıcı tek bir satıra sığmadığında, eşittir işaretinden (=
) sonra girin ve bir girinti kullanın.
private val defaultCharset: Charset? = EncodingRegistry.getInstance().getDefaultCharsetForPropertiesFiles(file)
get
ve/veya set
işlevi bildiren özelliklerin her birini
kendi satırında normal girinti (+4) ile gösterilir. Aynı kuralları kullanarak biçimlendirme
ekleyebilirsiniz.
var directory: File? = null set(value) { // … }
val defaultExtension: String get() = "kt"
Boşluk
Sektör
Tek bir boş satır görünür:
- Bir sınıfın ardışık üyeleri arasında: özellikler, kurucular,
fonksiyonlar, iç içe geçmiş sınıflar vb.
- İstisna: İki arasında boş bir satır ardışık özellikler (aralarında başka kod olmadan) isteğe bağlıdır. Bu tür boş satırlar, mülkler ve ilişkili özelliklerin mantıksal gruplamaları kendi arka mülkleriyle (varsa) ilişkilendirebilir.
- İstisna: Enum sabitleri arasındaki boş satırlar kapsam dahilindedir bölümüne göz atın.
- Kodu düzenlemek için gerektiğinde ifadeler arasında mantıksal alt bölümlere ayırır.
- İsteğe bağlı olarak, fonksiyondaki ilk ifadeden önce önce veya sınıftaki son üyeden sonra (ne teşvik ne de kırılmamalıdır).
- Bu belgenin diğer bölümlerinin ( Yapı bölümüne bakın).
Art arda birden fazla boş satıra izin verilir ancak kullanılması önerilmez veya gerek yoktur.
Yatay
Dil veya diğer stil kurallarının gerektirdiği yerlerde harflerden, yorumlardan ve KDoc'tan ayrı olarak, boşluk yalnızca aşağıdaki yerlerde görünür:
-
if
gibi ayrılmış kelimeleri ayırma,for
veyacatch
gelen bir açık parantezden ((
) sonra açar.// WRONG! for(i in 0..1) { }
// Okay for (i in 0..1) { }
else
veyacatch
, şuradan kapanış küme ayracı (}
) ekleyin.// WRONG! }else { }
// Okay } else { }
-
Herhangi bir açık küme parantezinden önce (
{
).// WRONG! if (list.isEmpty()){ }
// Okay if (list.isEmpty()) { }
-
İkili sayı operatörünün her iki tarafında da.
// WRONG! val two = 1+1
Bu durum, aşağıdaki "operatör benzeri" simgeler için de geçerlidir:// Okay val two = 1 + 1
- lambda ifadesindeki ok (
->
).// WRONG! ints.map { value->value.toString() }
// Okay ints.map { value -> value.toString() }
-
bir üye referansındaki iki iki nokta (
::
)// WRONG! val toString = Any :: toString
// Okay val toString = Any::toString
-
nokta ayırıcı (
.
).// 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 işaretinden (
:
) önce, yalnızca belirtmeye yönelik bir sınıf beyanında kullanılıyorsa temel sınıf veya arayüz ya dawhere
ifadesinde kullanıldığında şunun için: genel kısıtlamalara tabidir.// 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
-
Eğik çizginin (
//
) her iki tarafında, satır sonu yorumu. 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 teklif vermeyi zorunlu kılacak veya teklifte bulunmayacak şekilde yorumlanmaz satırın başında veya sonunda ek boşluk; yalnızca hedeflendiği için iç mekana sahip.
Belirli yapılar
Sıralama sınıfları
İşlevsiz ve sabit değerleriyle ilgili belge içermeyen bir enum isteğe bağlı olarak tek satır olarak biçimlendirilebilir.
enum class Answer { YES, NO, MAYBE }
Sıralamadaki sabit değerler ayrı satırlara yerleştirildiğinde, gövde tanımladığı durumlar dışında bunların arasında boş bir satır olması gerekmez.
enum class Answer { YES, NO, MAYBE { override fun toString() = """¯\_(ツ)_/¯""" } }
Sıralama sınıfları sınıf olduğundan biçimlendirme sınıflarına ilişkin 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 notlar tek bir satıra yerleştirilebilir.
@JvmField @Volatile var disposable: Disposable? = null
Bağımsız değişkeni olmayan tek bir ek açıklama varsa beyan ile aynı satıra yerleştirilebilir.
@Volatile var disposable: Disposable? = null @Test fun selectAll() { // … }
@[...]
söz dizimi yalnızca açık bir site kullanımı hedefiyle ve yalnızca
2 veya daha fazla ek açıklamayı bağımsız değişken olmadan tek bir satırda birleştirme.
@field:[JvmStatic Volatile] var disposable: Disposable? = null
Örtülü iade/mülk türleri
Bir ifade işlevi gövdesi veya özellik başlatıcı skaler ise değeri veya dönüş türü, gövdeden açıkça çıkarılabildiği için 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")
Kitaplık yazarken açık tür bildirimini koruyun: genel API'nin bir parçasıdır.
Adlandırma
Tanımlayıcılar yalnızca ASCII harfler ve rakamlar ile aşağıda belirtilen az sayıda durumda alt çizgi kullanır. Bu nedenle, her geçerli tanımlayıcı adı \w+
normal ifadesiyle eşleştirilir.
Örneklerde görülenlere benzer özel ön ekler veya son ekler
name_
, mName
, s_name
ve kName
, şu durumlar dışında kullanılmaz:
özellikleri (bkz.
Mülkleri destekleme).
Paket Adları
Paket adlarının tümü küçük harfle yazılır ve ardışık kelimeler basitçe kullanılır birleştirilmiş (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 isimlerden oluşur.
anlamına gelir. Örneğin, Character
veya ImmutableList
. Arayüz adları
aynı zamanda adlar veya isimlerden oluşan ifadeler de (örneğin, List
) olabilir, ancak
bazen sıfatlar veya sıfat ifadeler olabilir
(örneğin, Readable
).
Test sınıfları, test ettikleri sınıfın adından başlayarak adlandırılır.
ve Test
ile bitiyor. Örneğin, HashTest
veya
HashIntegrationTest
.
İşlev adları
İşlev adları büyük harfle yazılır ve genellikle fiil veya fiil kelime öbeklerinden oluşur. Örneğin, sendMessage
veya stop
.
Test işlevi adlarında, adın mantıksal bileşenlerini ayırmak için alt çizgi karakterlerinin kullanılmasına izin verilir.
@Test fun pop_emptyStack() { // … }
Unit
döndüren ve @Composable
ile açıklama eklenen işlevler PascalCased'dir ve tür gibi isim olarak adlandırılır.
@Composable fun NameTag(name: String) { // … }
İşlev adları boşluk içermemelidir, çünkü bu özellik tüm platformunda (özellikle de Android'de tam olarak desteklenmemektedir).
// WRONG! fun `test every possible case`() {} // OK fun testEveryPossibleCase() {}
Sabit adlar
Sabit adlarda UPPER_SNAKE_CASE kullanılır: tümü büyük harf, içeren bir liste oluşturabilirsiniz. Peki sabit değer tam olarak nedir?
Sabitler, özel get
işlevi olmayan ve içerikleri şu şekilde olan val
özellikleridir:
kalıcı olarak değişmez ve işlevlerinin yan etkiye sahip olmaması gerekir. Bu
sabit türler ve sabit tür koleksiyonları içerir.
const
olarak işaretlenirse skalerler ve dizeler de gösterilir. Örneklerden herhangi biri
gözlemlenebilir durum değişebilir, sabit değildir. Yalnızca
hiçbir zaman değiştirmeyin.
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 isimler veya isimlerden oluşur.
Sabit değerler yalnızca object
içinde tanımlanabilir
üst düzey bir bildirim olarak kabul edebilirsiniz. Bir
sabit olmayan ancak class
içinde tanımlanan bir ad sabit olmayan bir ad kullanmalıdır.
Skaler değer olan sabitler const
kullanmalıdır.
değiştirici.
Sabit olmayan adlar
Sabit olmayan adlar büyük/küçük harf düzeniyle 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 isimler veya isimlerden oluşur.
Mülkler yedekleniyor
Bir destek mülkü adı, gayrimenkulün adı ile tam olarak aynı olmalıdır. dışında bir alt çizgi kullanılamaz.
private var _table: Map<String, Int>? = null val table: Map<String, Int> get() { if (_table == null) { _table = HashMap() } return _table ?: throw AssertionError() }
Değişken adlarını 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 rakam (ör.
E
,T
,X
,T2
) - Sınıflar için kullanılan biçimde bir ad ve ardından büyük harf kullanımı
T
harfi (ör.RequestT
,FooBarT
)
Deve kılıfı
Bazen İngilizce bir kelime öbeğini büyük/küçük harfe dönüştürmenin birden fazla makul yolu vardır. Örneğin, kısaltmalar veya "IPv6" ya da "iOS" gibi alışılmadık yapılar mevcut olduğunda. Tahmin edilebilirliği iyileştirmek için aşağıdaki şemayı kullanın.
Adın düz yazı biçimiyle başlayın:
- Kelime öbeğini düz ASCII'ye dönüştürün ve tüm kesme işaretlerini kaldırın. Örneğin, "Müller'in algoritması", "Müleller algoritması" olabilir.
- Bu sonucu, boşluk ve kalan noktalama işaretlerine (genellikle tire) göre ayırarak kelimelere bölün. Önerilen: Herhangi bir kelime yaygın olarak kullanılan bir deve harfi haline gelmişse bunu oluşturan bileşenlere bölün (ör. “AdWords”, “reklam kelimeleri” haline gelir). "iOS" gibi bir kelimenin aslında tek başına büyük ve küçük harflerden ibaret olmadığını unutmayın; herhangi bir kurallara aykırı olduğu için bu öneri geçerli değil.
- Şimdi, her şeyi küçük harfle (kısaltmalar dahil) yapın, ardından aşağıdakilerden birini yapın:
- Pascal büyük harf oluşturmak için her kelimenin ilk karakterini büyük yapın.
- Elde edilen ilk karakter hariç her kelimenin ilk karakterini büyük harf yap büyük/küçük harfe duyarlıdır.
- Son olarak, tüm kelimeleri tek bir tanımlayıcıda birleştirin.
Orijinal kelimelerdeki büyük/küçük harf düzeninin neredeyse hiç dikkate alınmadığına dikkat edin.
Düzyazı biçimi | Doğru | Yanlış |
---|---|---|
"XML Http İsteği" | XmlHttpRequest |
XMLHTTPRequest |
"yeni müşteri kimliği" | newCustomerId |
newCustomerID |
"dahili kronometre" | innerStopwatch |
innerStopWatch |
"iOS'te IPv6'yı destekler" | supportsIpv6OnIos |
supportsIPv6OnIOS |
"YouTube içe aktarıcısı" | YouTubeImporter |
YoutubeImporter * |
(* Kabul edilebilir ancak önerilmez.)
Belgeler
Biçimlendirme
KDoc bloklarının temel biçimlendirmesi şu örnekte gösterilmiştir:
/** * Multiple lines of KDoc text are written here, * wrapped normally… */ fun method(arg: String) { // … }
...veya şu tek satırlık örnekte:
/** An especially short bit of KDoc. */
Temel biçim her zaman kabul edilir. Tek satırlı form
KDoc bloğunun tamamı (yorum işaretçileri dahil) olduğunda değiştirilir
tek bir satıra sığabilir. Bunun yalnızca
@return
gibi blok etiketleri engeller.
Paragraf
Tek boş satır; yani yalnızca başında hizalı yıldız işareti içeren bir satır
(*
)—Paragraflar arasında ve varsa blok etiketleri grubundan önce görünür.
Etiketleri engelle
Kullanılan standart "engelleme etiketlerinin" herhangi biri
@constructor
, @receiver
, @param
, @property
, @return
,
@throws
, @see
ve bunlar hiçbir zaman boş bir açıklamayla görünmez.
Bir engelleme etiketi tek bir satıra sığmadığında,
devam çizgileri, @
konumundan 4 boşluk girintilidir.
Özet parçası
Her KDoc bloğu kısa bir özet parçasıyla başlar. Bu parça çok önemlidir: metinde görünen tek bölümdür bazı bağlamlarda (ör. sınıf ve yöntem dizinleri) kullanılabilir.
Bu, tam bir cümle değil, bir parça (ad) kelime öbeği veya fiil ifadesidir.
"A `Foo` is a...
" ile başlamıyor,
veya "This method returns...
",
zorunluluk içeren bir cümle oluşturmadığı veya
"Save the record.
". Ancak, parça büyük harfle yazılmıştır ve
tam bir cümleymiş gibi noktalama işaretleri var.
Kullanım
KDoc, en azından her public
türü için mevcuttur.
ve bu türdeki her public
veya protected
üye için
aşağıda belirtilen birkaç istisna ile uyumludur.
İstisna: Kendini açıklayan fonksiyonlar
KDoc, getFoo
gibi "basit, bariz" işlevler için isteğe bağlıdır
ve foo
gibi mülklerde gösterilebilir.
Bu istisnanın, alakalı bir kaydın atlanmasını haklı çıkarmak için kullanılması uygun değildir
standart bir okuyucunun bilmesi gereken
bilgiler arasında yer alır. Örneğin,
getCanonicalName
adlı bir işlev veya canonicalName
adlı bir özellik,
belgeyi atlamayın (bunların mantığından dolayı, belgenin
/** Returns the canonical name. */
) genel bir okuyucuda
"kurallı ad" teriminin ne olduğu anlamına geliyor!
İstisna: geçersiz kılmalar
KDoc, bir süper tür yöntemini geçersiz kılan bir yöntemde her zaman mevcut değildir.