Belge yönergeleri


İşlevsellik ve işaretleme

Bu bölümde sık ihtiyaç duyulan özellikler açıkmektedir. Nasıl olduklarını görmek için sayfanın kaynak koduna bakın.

  1. Numaralı listeler
    1. En az 3 başında boş alan olan iç içe numaralanmış listeler
    2. Kodda gerçek sayı ilgisizdir; ayrıştırma, doğru öğe numarasını ayarlamayla ilgilenecek.
  • Madde işareti listeleri
    • İç içe madde işareti listeleri
  • **çift yıldız** ile kalın metin
  • _underscore_ veya *single asterisk* ile italik metin
  • highlighted as code'Backquotes kullanarak' bir cümle içindeki metin
  • Belge sayfalarının bağlantıları MRTK belge yönergeleri
  • Bir sayfa içindeki yer noktalarının bağlantıları; yer sabit noktaları, boşlukların tirelerle değiştirilmesi ve küçük harfe dönüştürülmesiyle oluşturulur

Kod örnekleri için üç '' backtick olan blokları kullanır ve söz dizimi vurgulama için dil olarak csharp belirtiriz:

int SampleFunction(int i)
{
   return i + 42;
}

Bir cümle içinde koddan use a single backtick bahsederek.

Todos

Belgelerde TODO'ları kullanmaktan kaçının çünkü zaman içinde bu TODO'lar (kod TODO'ları gibi) birikebilir ve bunların nasıl güncelleştirilması gerektiği ve neden kaybedilacağı hakkında bilgi içerir.

ToDO eklemek kesinlikle gerekli ise şu adımları izleyin:

  1. Github'da TODO'nun arkasındaki bağlamı açıklayan yeni bir sorun kaydedin ve başka bir katkıda bulunandan toDO'yu anlama ve sonra ele alma hakkında yeterli arka plan bilgileri girin.
  2. Belgelerde todo içinde sorun URL'sini kullanın.

<!-- TODO: https://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE Sorun hakkında kısa bir açıklama -->

Vurgulanan bölümler

Okuyucuya belirli noktaları vurgulamak için [! NOT] , [! UYARI] ve [! ÖNEMLİ] ile aşağıdaki stillerin üretebilirsiniz. Yalnızca özel ilgili durumlar için genel noktalar ve uyarı/önemli noktalar için notlar kullanılması önerilir.

Not

Not örneği

Uyarı

Uyarı örneği

Önemli

Önemli bir açıklama örneği

Sayfa düzeni

Giriş

Ana bölüm başlığının hemen sonrasındaki bölüm, bölümün ne hakkında olduğunu kısa bir tanıtım olarak ifade etmektir. Bunu çok uzun hale değil, bunun yerine alt başlıkları ekleyin. Bunlar bölümlere bağlantı sağlar ve yer işareti olarak kaydedilebilir.

Ana gövde

Gerisini yapılandıran iki düzeyli ve üç düzeyli başlıkları kullanın.

Mini Bölümler

Öne çıkmaları gereken bloklar için kalın bir metin satırı kullanın. Bunu bir noktada dört düzeyli başlıklarla değiştirebiliriz.

'Ayrıca bakın' bölümü

Çoğu sayfa, Ayrıca bkz. adlı bir bölümle bitimli. Bu bölüm, bu konu başlığıyla ilgili sayfaların bağlantılarının madde işaretli bir listesidir. Bu bağlantılar uygun olduğunda sayfa metni içinde de görünebilir, ancak bu gerekli değildir. Benzer şekilde, sayfa metni ana konu başlığıyla ilgili sayfaların bağlantılarını içerebilir; bunlar Ayrıca bkz. listesine dahil değildir. Bağlantı seçimine örnek olarak bu sayfanın ''Ayrıca bkz.'' bölümü.

İçindekiler Tablosu (İçindekiler)

Toc dosyaları, MRTK belgelerinde gezinti çubukları oluşturmak github.io kullanılır. Her yeni belge dosyası ekleniyorsa, belge klasörünün toc.yml dosyalarından birinin içinde bu dosya için bir giriş olduğundan emin olun. Geliştirici belgelerinin gezintisinde yalnızca toc dosyalarında listelenen makaleler gösterilir. Belge klasöründeki her alt klasör için bir toc dosyası olabilir. Bu dosya, var olan herhangi bir toc dosyasına bağlanarak gezintinin ilgili parçasına bir alt bölüm olarak eklemenizi sağlar.

Stil

Yazma stili

Genel kural: Profesyonel olarak ifade etmeye çalış. Bu genellikle 'konuşma tonlarından' kaçınma anlamına gelir. Ayrıca hiperbolik ve duyarlılıktan kaçınmaya da çalış.

  1. Fazla (aşırı) bir şey olmaya çalışma.
  2. Hiçbir zaman 'I' yazma
  3. 'Biz'den kaçının. Bu, genellikle 'MRTK' kullanılarak kolayca yeniden ifade edilebilir. Örnek: "Bu özelliği destekliyoruz" - "MRTK bu özelliği destekliyor" veya > "aşağıdaki özellikler de destekle....
  4. Benzer şekilde, 'siz' ile kaçınmaya çalış. Örnek: "Bu basit değişiklikle gölgelendiriciniz yapılandırılabilir hale gelir!" - "Gölgelendiriciler çok az > çabayla yapılandırılabilir hale gelir."
  5. 'Özensiz tümcecikler' kullanma.
  6. Aşırı heyecanlanmamak için herhangi bir şey satmamız gerek yok.
  7. Benzer şekilde aşırı çarpıcı olmaktan kaçının. Ünlem işaretine nadiren ihtiyaç duyulr.

Büyük harf

  • Tümce büyük/büyük harflerini kullanın. Yani. İlk harfi ve adları büyük harfle yazın ancak başka bir şey yoktur.
  • Diğer her şey için normal İngilizce kullanın. Başka bir deyişle, bu bağlamda özel biranlamı olsalar bile rastgele sözcükleri büyük harfle ifade etmek yoktur. Belirli sözcükleri vurgulamak için italik metni tercih edin, aşağıya bakın.
  • Bir bağlantı bir cümleye ekli olduğunda (tercih edilen yöntem), standart bölüm adı her zaman büyük harf kullanır ve bu nedenle metin içinde rastgele büyük harf kullanma kuralını bozan bir kuraldır. Bu nedenle büyük/küçük harf kullanımını düzeltmek için özel bir bağlantı adı kullanın. Örnek olarak, sınır denetimi belgelerinin bağlantısı burada velanmıştır.
  • Unity gibi adları büyük harfle ifade etmek.
  • Unity düzenleyicisi yazarken "düzenleyiciyi" büyük harfle yazmayın.

Vurgu ve vurgulama

Sözcükleri vurgulamanın veya vurgulamanın iki yolu vardır: kalın hale veya italik yapma. Kalın metnin etkisi, kalın metnin dışarı doğru kayması ve bu nedenle bir metin parçasının kayması ve hatta yalnızca bir sayfayı kaydırma sırasında kolayca fark edilebilir olmasıdır. Kalın, insanların hatırlaması gereken tümcecikleri vurgulamak için harikadır. Ancak, genellikle dikkat dağıtıcı olduğu içinkalın metinleri nadiren kullanın.

Genellikle biri mantıksal olarak birlikte ait olan bir şeyi 'grupla' veya özel bir anlamı olduğundan belirli bir terimi vurgulamak ister. Bu tür şeyler genel metinden farklı olmak zorunda değildir. Bir şeyi vurgulamak için basit bir yöntem olarak italik metin kullanın.

Benzer şekilde, metinde bir dosya adı, yol veya menü girişi belirtildiğinde, dikkat dağıtmadan bunu mantıksal olarak gruplama italik yapmak tercih eder.

Genel olarak, gereksiz metin vurgulamalarından kaçınmaya çalış. Okuyucuyu haberdar etmek için özel terimler bir kez vurgulanabilir, metin boyunca bu tür vurgulamaları tekrarlamaz, artık bir amaca hizmet etmiyorsa ve yalnızca dikkati dağıtıyorsa.

Menü girişlerini bahsetme

Kullanıcının tıklaması gereken bir menü girdisini ifade ediyorken geçerli kural şu şekildedir: Project Dosyalar Yaprak >> Oluştur

Diğer sayfalara mümkün olduğunca çok yararlı bağlantı ekler, ancak her bağlantı yalnızca bir kez kullanılır. Bir okuyucunun sayfanın her bağlantısına tıklar ve aynı sayfanın 20 kez açılmasının ne kadar rahatsız edici olacağını düşünebilirsiniz.

Bir cümleye eklenmiş bağlantıları tercih edin:

  • BAD: Yönergeler yararlıdır. Ayrıntılar için bu bölüme bakın.
  • GOOD: Yönergeler yararlıdır.

Dış bağlantılardan kaçının; bunlar zaman dışı olabilir veya telif hakkıyla korunan içerik içerebilir.

Bir bağlantı eklenirken aynı zamanda Ayrıca bkz . bölümünde da listelenmiş olup olmadığına dikkat edin. Benzer şekilde, yeni sayfa bağlantısının bağlantılı sayfaya eklenip eklenmeyeceğini kontrol edin.

Görüntüler/ekran görüntüleri

Ekran görüntülerini gelişigüzel kullanın. Belgelerde görüntülerin sürdürülmesi çok fazla iş, küçük Kullanıcı arabirimi değişiklikleri çok sayıda ekran görüntüsünü güncel hale getirebilirsiniz. Aşağıdaki kurallar bakım çabalarını azaltır:

  1. Metinde açıklanabildiği şeyler için ekran görüntülerini kullanmayın. Özellikle, özellik adlarını ve değerlerini göstermek için özellik kılavuzunun hiçbir koşulda ekran görüntüsü .
  2. Gösterildiklere ilgisiz olan bir ekran görüntüsüne dahil etme. Örneğin, bir işleme etkisi gösterildiğinde görünüm penceresinin ekran görüntüsünü oluşturun, ancak bunun çevresindeki Kullanıcı arabirimini hariç tutun. Bazı Kullanıcı arabirimini gösteren bir pencere, yalnızca ilgili önemli bölümü görüntüde olacak şekilde taşımayı deneyin.
  3. Ekran görüntüsü Kullanıcı arabirimi dahil edildiğinde yalnızca önemli bölümleri gösterir. Örneğin, bir araç çubuğundaki düğmeler hakkında konuştuğu zaman, önemli araç çubuğu düğmelerini gösteren küçük bir görüntü oluşturun, ancak çevresindeki her şeyi hariç tutun.
  4. Yalnızca yeniden oluşturulması kolay olan görüntüleri kullanın. Yani, ekran görüntülerine işaretçileri veya vurguları boyamayın. İlk olarak, bunların her ne kadar görünmesi gerektiği tutarlı kurallar yoktur. İkincisi, bu ekran görüntüsünü tekrar oluşturma ek çabadır. Bunun yerine, önemli bölümleri metinde açıklama yapın. Bu kural için özel durumlar vardır ancak bunlar nadir bir durumdur.
  5. Kuşkusuz, animasyonlu bir GIF 'i yeniden oluşturmaya çok daha fazla çaba vardır. Zaman sonuna kadar yeniden oluşturmanız veya kişilerin bu süreyi harcamaya gerek yoksa onları oluşturması bekleninceye kadar sorumlusunuz.
  6. Bir makaledeki görüntü sayısını düşük tutun. Genellikle iyi bir yöntem, bazı araçlardan oluşan genel bir ekran görüntüsü oluşturmak, her şeyi gösteren ve daha sonra kalanı metinde tanımlıyor. Bu, gerektiğinde ekran görüntüsünü değiştirmeyi kolaylaştırır.

Diğer bazı yönleri:

  • Ekran görüntüleri için düzenleyici Kullanıcı arabirimi, tüm kullanıcıların koyu renkli temaya erişimi olmadığından ve işleri mümkün olduğunca tutarlı tutmak istiyoruz. açık gri Tema Düzenleyicisi kullanmalıdır.
  • Varsayılan görüntü genişliği 500 pikseldir, bu da çoğu monitörde iyi görüntülenir. Bundan çok büyük bir farklılık yapmayı deneyin. 800 piksel genişliği en büyük değer olmalıdır.
  • Kullanıcı arabiriminin ekran görüntüleri için PNG 'leri kullanın.
  • 3B Görünüm penceresi ekran görüntüleri için PNGs veya JPGs kullanın. Sıkıştırma oranına göre kaliteyi tercih edin.

Bileşen özellikleri listesi

Bir özellik listesini belgeleme sırasında, özellik adını vurgulamak için kalın metin kullanın, daha sonra satır sonlarını ve bunları anlatmak için normal metni kullanın. Alt bölümleri veya madde işareti noktası listelerini kullanmayın.

Ayrıca, tüm cümleleri bir noktayla tamamlamayı unutmayın.

Sayfa tamamlama denetim listesi

  1. Bu belge yönergelerinin izlendiğinden emin olun.
  2. Belge yapısına gözatıp, yeni belgenin diğer sayfaların Ayrıca gör bölümünün altında olup olmadığını görün.
  3. Varsa, konuyla ilgili bilgi sahibi olan birisine teknik doğruluk için sayfayı okuyun.
  4. Stil ve biçimlendirme için bir kişi için sayfayı okumaya devam edin. Bu, konu başlığı altında olmayan bir kişi olabilir ve bu da belge ne kadar kolay bir şekilde ele alındığı hakkında geri bildirim almak için iyi bir uygulamadır.

Kaynak belge

API belgeleri MRTK kaynak dosyalarından otomatik olarak oluşturulacaktır. Bunu kolaylaştırmak için, kaynak dosyalarının aşağıdakileri içermesi gerekir:

Yukarıdaki ' a ek olarak, kod, bakım, hata düzeltmeleri ve özelleştirme kolaylığına izin vermek için iyi açıklamalı olmalıdır.

Class, struct, enum Özet blokları

MRTK öğesine bir sınıf, yapı veya Enum eklenirse, amacı açıklanmalıdır. Bu, sınıfın üzerindeki bir Özet bloğunun formunu almak için kullanılır.

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

Herhangi bir sınıf düzeyi bağımlılığı varsa, bunların hemen altındaki bir açıklama bloğunda Açıklanmaları gerekir.

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

Sınıflar, yapılar veya Numaralandırmalar için Özet olmadan gönderilen çekme Istekleri onaylanmayacak.

Özellik, yöntem, olay Özet blokları

Özellikler, Yöntemler ve Olaylar (PMEs) ve alanlar, kod görünürlüğü ne olursa olsun, Özet bloklarla açıklanacaktır (genel, özel, korumalı ve iç). Belge oluşturma aracı yalnızca ortak ve korunan özellikleri filtrelemeden ve yayımmaktan sorumludur.

Not: Unity metotları için bir Özet bloğu gerekmez ( örn: uyanık, Başlat, Güncelleştir).

Çekme isteğinin onaylanabilmesi için PME belgeleri gereklidir .

Bir PME Özeti bloğunun bir parçası olarak, parametrelerin anlamı ve amacı ve döndürülen veriler gereklidir.

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

Özellik giriş sürümü ve bağımlılıklar

API Özet belgelerinin bir parçası olarak, özelliğin tanıtılma MRTK sürümü ile ilgili bilgiler ve tüm bağımlılıklar bir açıklama bloğunda belgelenmelidir.

Bağımlılıklar uzantı ve/veya platform bağımlılıklarını içermelidir.

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

Serileştirilmiş alanlar

Bir komut dosyasının Inspector 'daki alanları için çalışma zamanı belgelerini sağlamak üzere Unity 'nin araç ipucu özniteliğini kullanmak iyi bir uygulamadır.

Yapılandırma seçeneklerinin API belgelerine dahil edilmesini sağlamak için, komut dosyalarının bir Özet bloğunda en azından araç ipucu içeriğini içermesi gerekir.

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

Sabit listesi değerleri

Ve numaralandırma kullanılırken, kod ayrıca bir Özet bloğu kullanarak Enum değerlerinin anlamını belgelemesi gerekir. Açıklamalar blokları, isteğe bağlı olarak daha fazla bilgi sağlamak için kullanılabilir.

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

Nasıl yapılır belgeleri

Karma Gerçeklik araç setinin birçok kullanıcısı API belgelerini kullanmak zorunda kalabilir. Bu kullanıcılar, deneyimlerini oluşturmak için önceden hazırlanmış, yeniden kullanılabilir olan ön ve betiklerimizden faydalanır.

Her özellik alanı, oldukça yüksek düzeyde betimleyen bir veya daha fazla markı (. MD) dosyası, ne sağlandığını içerir. Belirli bir özellik alanının boyutuna ve/veya karmaşıklığına bağlı olarak, her özellik için en çok bir özelliğe kadar ek dosya gereksinimi olabilir.

Bir özellik eklendiğinde (veya kullanım değiştirildiğinde), genel bakış belgelerinin sağlanması gerekir.

Bu belgenin bir parçası olarak, bir özellik veya kavramın çalışmaya başlama bölümünde müşterilerine yardımcı olmak için çizimler dahil olmak üzere nasıl yapılır bölümlerinin sağlanması gerekir.

Tasarım belgeleri

Karma Gerçeklik tamamen yeni bir iş LDS oluşturma fırsatı sağlar. Bunun bir bölümü, MRTK ile kullanmak üzere özel varlıkların oluşturulmasını içerebilir. Bunu, müşteriler için mümkün olduğunca fazla ücretsiz hale getirmek için, bileşenler, resim varlıkları için herhangi bir biçimlendirmeyi veya diğer gereksinimleri açıklayan tasarım belgeleri sağlamalıdır.

Tasarım belgelerinin yararlı olabilecek bazı örnekler:

  • İmleç modelleri
  • Uzamsal eşleme görselleştirmeleri
  • Ses efekti dosyaları

Bu belge türü kesinlikle önerilir ve çekme isteği incelemesinin bir parçası olarak istenebilir.

Bu, MS geliştirici sitesindeki tasarım önerisinden farklı olabilir veya olmayabilir

Performans notları

Bazı önemli özellikler bir performans maliyetiyle gelir. Genellikle bu kod, nasıl yapılandırıldığına bağlı olarak değişir.

Örnek:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

Performans notları, CPU ve/veya GPU ağır bileşenleri için önerilir ve çekme isteği incelemesinin bir parçası olarak istenebilir. Geçerli performans notları API ve genel bakış belgelerine dahil edilir.

Yeni değişiklikler

Son değişiklikler belgeleri, her bir özellik alanının bireysel breaking-changes.md bağlantısı olan üst düzey bir dosyadan oluşur.

Özellik alanı breaking-changes.md dosyaları, belirli bir sürüm için bilinen tüm büyük değişikliklerin listesini ve geçmiş sürümlerden gelen son değişiklik geçmişini içerir.

Örnek:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

Özellik düzeyi breaking-changes.md dosyaları içinde yer alan bilgiler, her yeni MRTK sürümü için sürüm notlarına toplanacaktır.

Bir değişikliğin parçası olan tüm önemli değişiklikler, çekme Isteğinin bir parçası olarak belgelenmelidir .

Markın düzenlemesi araçları

Visual Studio Code, MRTK belgelerinin parçası olan markdown dosyalarını düzenlemek için harika bir araçtır.

Belge yazarken, aşağıdaki iki uzantıyı yüklemek de kesinlikle önerilir:

  • Visual Studio Code için Docs Markdown Uzantısı - Belge yazma seçenekleri menüsünü getirmek için Alt+M'yi kullanın.

  • Kod Yazım Denetleyicisi - yanlış yazılmış sözcüklerin altı çizili olur; yanlış yazılmış bir sözlüğe sağ tıklar ve sözlüğünü değiştirir veya sözlüğe kaydedebilirsiniz.

Bunların ikisi de Microsoft tarafından yayımlanan Docs Yazma Paketi'ne paketlenmiştir.

Ayrıca bkz.

MRTK

Bu belgede Karma Gerçeklik Araç Seti'ne (MRTK) ilişkin belge yönergeleri ve standartları açıklanmıştır. Bu, yaygın tuzakları vurgulamak ve önerilen yazma stilini açıklamak için belge yazma ve oluşturmanın teknik yönlerine giriş sağlar.

Sayfanın örnek olarak görev yapacak olması gerekir, bu nedenle belgelerin hedeflenen stilini ve en yaygın işaretleme özelliklerini kullanır.