Aptana Journal #11: Menambahkan Dukungan Inline JSDoc


Artikel sebelumnya adalah salah satu post yang menarik di akhir tahun 2012 ini karena artikel tersebut adalah artikel ke-212 yang saya tulis di blog ini🙂

Post ke 212 Untuk Seri ke 10 Di Akhir Tahun 2012

Post ke 212 Untuk Seri ke 10 Di Akhir Tahun 2012

Dan kembali ke artikel 213,  saya dihadapkan permasalahan bagaimana menampilkan content assist untuk argumen dalam anonymous inner function, misalnya yang paling sering ditemui adalah jQuery.Event.  Sebagai contoh, content assist tidak bekerja dengan baik di gambar berikut ini:

Content Assist Tidak Menampilkan proposal untuk object jQuery.Event

Content Assist Tidak Menampilkan proposal untuk object jQuery.Event

Padahal, e adalah sebuah variabel dengan tipe jQuery.Event. Dan saya sudah menambahkan bagian berikut ini ke ScriptDoc XML yang dipakai:

<javascript>
   ... <!-- isi diabaikan -->

   <class type="jQuery.Event">
     <properties>
        <property name="currentTarget" type="Element" scope="instance">
           <description>The current DOM element within the event bubbling phase.</description>
        </property>
     </properties>
   </class>
</javascript>

Dalam bahasa seperti JavaScript, memang sangat sulit untuk menentukan apa tipe dari sebuah variabel.  Tapi, bila programmer JavaScript menambahkan sebuah komentar dengan makna khusus, misalnya JSDoc, maka Aptana Studio bisa mengetahui tipe dari variabel e dan menampilkan content assist untuk variabel tersebut.  Saat ini, Aptana Studio mendukung penggunaan @type untuk elemen selain function sehingga content assist bekerja dengan baik bila saya menambahkan JSDOC tersebut seperti berikut ini:

Menggunakan JSDoc @type di Aptana Studio

Menggunakan JSDoc @type di Aptana Studio

Tapi saya merasa syntax tersebut masih terlalu panjang.  Oleh sebab itu, saya mencoba memodifikasi Aptana Studio agar mendukung inline JSDoc yang lebih singkat.

Hasil penelusuran membawa saya ke class JSTypeUtil di method applyDocumentation(). Method ini akan memeriksa apakah property adalah FunctionElement. Bila iya, maka ia akan memberikan dokumentasi untuk FunctionElement tersebut.  Jika bukan, ia memberikan dokumentasi ke PropertyElement yang ada berdasarkan block.getText(), block.getTags(TagType.TYPE), dan block.getTags(TagType.EXAMPLE) (dimana block adalah sebuah DocumentationBlock).

Untuk mendukung inline JSDOC, saya perlu mengubah alur di atas,  sehingga kode program akan terlihat seperti berikut ini:

public static void applyDocumentation(PropertyElement property, JSNode node, DocumentationBlock block)
{
   if (property instanceof FunctionElement)
   {
       ... // kode program diabaikan
   }
   else
   {
       if (block != null)
       {
           // Bila tidak ada tag TYPE, maka ini adalah sebuah inline JSDOC
           if (block.getTags(TagType.TYPE).isEmpty()) {
              if (!StringUtil.isEmpty(block.getText().trim())) {
                 property.addType(block.getText().trim());
              }
           } else {

              ... // ini adalah kode program semula
           }
       }
   }
}

Sekarang, bila saya memakai inline JSDoc, maka content assist akan bekerja sesuai dengan yang diharapkan seperti pada gambar berikut ini:

Content Assist Untuk Inline JSDoc

Content Assist Untuk Inline JSDoc

Ops!  Tunggu dulu..  Bila saya memperhatikan contoh inline JSDoc di halaman http://code.google.com/p/jsdoc-toolkit/wiki/InlineDocs, terlihat bahwa tidak ada spasi di antara tipe dan komentar.  Versi perubahan saya saat ini masih tidak compatible.

Oleh sebab itu, saya masih perlu melakukan perubahan.  Saya harus mengubah SDoc.flex  dan SDoc.grammar agar mengenali inline JSDoc yang tidak dipisahkan dengan spasi.

Saya mulai dengan menambahkan sebuah definisi terminal baru di /com.aptana.js.core/parsing/SDoc.flex dengan nama INLINE_DOCUMENTATION seperti berikut ini:

%terminals INLINE_DOCUMENTATION;

Lalu, pada definisi rule Block, saya mengubahnya sehingga terlihat seperti berikut ini:

Block
	=	START_DOCUMENTATION Text.text END_DOCUMENTATION
		{:
			return new DocumentationBlock((String) text.value);
		:}
	|	START_DOCUMENTATION Tags.tags END_DOCUMENTATION
		{:
			return new DocumentationBlock((List<Tag>) tags.value);
		:}
	|	START_DOCUMENTATION Text.text Tags.tags END_DOCUMENTATION
		{:
			return new DocumentationBlock((String) text.value, (List<Tag>) tags.value);
		:}
	|	INLINE_DOCUMENTATION.text
	    {:
	    	return new InlineDocumentationBlock((String)text.value);
	    :}
	;

Pada kode program di atas, saya memisahkan antara dokumentasi biasa yang diwakili oleh class DocumentationBlock dan dokumentasi inline yang diwakili oleh class InlineDocumentationBlock.   Saat ini class InlineDocumentationBlock belum ada, sehingga saya perlu membuatnya.   Karena InlineDocumentationBlock pada dasarnya adalah bentuk khusus dari DocumentationBlock, maka saya tinggal menurunkan class tersebut dari DocumentationBlock.   Class baru ini dibuat di package com.aptana.js.internal.core.parsing.sdoc.model di proyek com.aptana.js.core dengan isi seperti berikut ini:

package com.aptana.js.internal.core.parsing.sdoc.model;

/**
 * Model to represent inline doc comments. See 
 * <a href="http://code.google.com/p/jsdoc-toolkit/wiki/InlineDocs">
 * http://code.google.com/p/jsdoc-toolkit/wiki/InlineDocs</a> for example.
 * 
 * @author SolidSnake
 *
 */
public class InlineDocumentationBlock extends DocumentationBlock {

	public InlineDocumentationBlock(String content) {
		super(content);
	}

}

Setelah itu, pada file /com.aptana.js.core/com/aptana/js/internal/core/parsing/sdoc/SDocTokenType.java, di bagian enumeration SDocTokenType, saya menambahkan baris berikut ini:

  INLINE_DOCUMENTATION(Terminals.INLINE_DOCUMENTATION),

Lalu, saya melakukan perubahan di file , dengan menambahkan baris berikut ini di <YYINITIAL>:

  // inline documentation
  "/**" [^ \t\r\n{\[\]#]+ "*/"  {
	String text = yytext(); 
	return newToken(SDocTokenType.INLINE_DOCUMENTATION, text.substring(3,text.length()-2)); }

Perubahan pada scanner generator dan parser generator telah selesai, saya pun mencoba menjalankan build.js.xml untuk memastikan bahwa file Java bisa dihasilkan dengan baik.  Caranya adalah dengan men-klik kanan file build.js.xml, kemudian memilih Run As, Ant Build.  Setelah memastikan bahwa Console menampilkan tulisan BUILD SUCCESSFUL,  saya mencoba me-refresh package com.aptana.js.internal.core.parsing.sdoc dengan men-klik kanan package tersebut dan memilih Refresh.

Perubahan terakhir yang perlu saya lakukan kembali lagi ke class JSTypeUtil di method applyDocumentation(). Saya kembali mengubah method tersebut sehingga terlihat seperti berikut ini:

public static void applyDocumentation(PropertyElement property, JSNode node, DocumentationBlock block)
{
  if (property instanceof FunctionElement)
  {
    applyDocumentation((FunctionElement) property, node, block);
  }
  else
  {
    if (block != null)
    {
      if (block instanceof InlineDocumentationBlock) {

        if (!StringUtil.isEmpty(block.getText().trim())) {
          property.addType(block.getText().trim());
        }

      } else {

        // apply description
        property.setDescription(block.getText());

        // apply types
        for (Tag tag : block.getTags(TagType.TYPE))
        {
          TypeTag typeTag = (TypeTag) tag;

          for (Type type : typeTag.getTypes())
          {
            ReturnTypeElement returnType = new ReturnTypeElement();

            returnType.setType(type.toSource());
            returnType.setDescription(typeTag.getText());
            property.addType(returnType);
          }
        }

        // apply examples
        for (Tag tag : block.getTags(TagType.EXAMPLE))
        {
          ExampleTag exampleTag = (ExampleTag) tag;

          property.addExample(exampleTag.getText());
        }

      }
    }
  }
}

Sekarang, inline JSDoc bisa bekerja dengan baik seperti yang terlihat pada gambar berikut ini:

Inline JSDoc yang bekerja dengan baik

Inline JSDoc yang bekerja dengan baik

Perihal Solid Snake
I'm nothing...

2 Responses to Aptana Journal #11: Menambahkan Dukungan Inline JSDoc

  1. Wahid Hahahuhu mengatakan:

    hei….boleh tau g’ syp penulis dibalik sana…
    kok g ada profilnya ????
    hehe

Apa komentar Anda?

Please log in using one of these methods to post your comment:

Logo WordPress.com

You are commenting using your WordPress.com account. Logout / Ubah )

Gambar Twitter

You are commenting using your Twitter account. Logout / Ubah )

Foto Facebook

You are commenting using your Facebook account. Logout / Ubah )

Foto Google+

You are commenting using your Google+ account. Logout / Ubah )

Connecting to %s

%d blogger menyukai ini: