অ্যাপস স্ক্রিপ্টে JSDoc

গুগল শিটস UI-তে ডকুমেন্টেশন, এবং স্ক্রিপ্ট-স্তরের অ্যানোটেশন।

গুগল অ্যাপস স্ক্রিপ্ট আপনার স্ক্রিপ্টের জন্য ডকুমেন্টেশন এবং অটোকমপ্লিট তৈরি করতে JSDoc ব্যবহার করে। কমেন্ট ব্যবহার করে জাভাস্ক্রিপ্ট কোডের ডকুমেন্টেশন করার জন্য JSDoc একটি স্ট্যান্ডার্ড।

অ্যাপস স্ক্রিপ্টে, JSDoc প্রধানত এই উদ্দেশ্যগুলো পূরণ করে:

1. এডিটরে স্বয়ংক্রিয় সম্পূর্ণকরণ : টাইপ করার সাথে সাথে প্যারামিটারের ইঙ্গিত এবং ফাংশনের বিবরণ প্রদান করে।
2. গুগল শিটসে কাস্টম ফাংশন : আপনার কাস্টম ফাংশনগুলোর ডকুমেন্টেশন তৈরি করা, যাতে সেগুলো শিটস ফর্মুলা হেল্পারে প্রদর্শিত হয়।
3. স্ক্রিপ্ট-স্তরের টীকা : অনুমোদন-এর মতো স্ক্রিপ্ট-ব্যাপী আচরণ নিয়ন্ত্রণ করতে বিশেষ ট্যাগ ব্যবহার করা।

ডকুমেন্ট ফাংশন

কোনো ফাংশনের ডকুমেন্টেশন তৈরি করতে, ফাংশন ডিক্লারেশনের ঠিক উপরে একটি JSDoc কমেন্ট ব্লক বসান। একটি JSDoc কমেন্ট /** দিয়ে শুরু হয় এবং */ দিয়ে শেষ হয়।

/**
 * Multiplies an input value by 2.
 *
 * @param {number} input The value to multiply.
 * @return {number} The input multiplied by 2.
 */
function double(input) {
  return input * 2;
}

আপনি যখন এইভাবে কোনো ফাংশনের ডকুমেন্টেশন তৈরি করেন, তখন অ্যাপস স্ক্রিপ্ট এডিটরে ফাংশনটি রেফারেন্স করার সময় একটি ডকুমেন্টেশন টুলটিপ দেখানো হয়। উদাহরণস্বরূপ, আপনি যখন এডিটরে double( টাইপ করেন, তখন আপনি দেখতে পাবেন:

ডাবল(ইনপুট)

ইনপুট মানকে ২ দ্বারা গুণ করে।

ইনপুট : সংখ্যা — যে মানটি গুণ করতে হবে।

সাধারণ ট্যাগ

ওভারলোড এবং একাধিক প্রকার

যদিও জাভাস্ক্রিপ্ট ক্লাসিক্যাল ফাংশন ওভারলোডিং (একই নামে একাধিক ফাংশন তৈরি করা) সমর্থন করে না, তবুও আপনি এমন একটি ফাংশন লিখতে পারেন যা বিভিন্ন ধরণের ইনপুট পরিচালনা করতে পারে। আপনি JSDoc-এ এই "ওভারলোডেড" আচরণগুলো নথিভুক্ত করতে পারেন।

ইউনিয়ন প্রকার

যদি কোনো প্যারামিটার বা রিটার্ন ভ্যালু একাধিক টাইপের হতে পারে, তাহলে একটি ইউনিয়ন টাইপ তৈরি করতে পাইপ ( | ) ব্যবহার করুন। অ্যাপস স্ক্রিপ্টে এমন ফাংশনগুলোর জন্য এটি প্রচলিত, যেগুলো একটিমাত্র ভ্যালু অথবা একাধিক ভ্যালুর একটি রেঞ্জ (যা একটি 2D অ্যারে হিসেবে উপস্থাপিত হয়) গ্রহণ করতে পারে।

/**
 * Multiplies an input value (or a range of values) by 2.
 *
 * @param {number|number[][]} input The value or 2D array to multiply.
 * @return {number|number[][]} The result.
 */
function double(input) {
  return Array.isArray(input) ?
      input.map(row => row.map(cell => cell * 2)) :
      input * 2;
}

@overload সহ একাধিক স্বাক্ষর

জটিল সিগনেচারযুক্ত ফাংশনগুলির ক্ষেত্রে, যেখানে অনুমোদিত প্যারামিটারগুলি একে অপরের উপর নির্ভরশীল, সেখানে আপনি প্রতিটি স্বতন্ত্র সিগনেচার সংজ্ঞায়িত করতে @overload ট্যাগ ব্যবহার করতে পারেন। আপনি ফাংশনের কোন সংস্করণটি কল করছেন তার উপর ভিত্তি করে নির্দিষ্ট ইঙ্গিত প্রদান করার জন্য অ্যাপস স্ক্রিপ্ট এডিটর এগুলি ব্যবহার করে।

/**
 * @overload
 * @param {string} name The name of the property to get.
 * @return {string} The property value.
 */
/**
 * @overload
 * @param {number} index The index of the item to get.
 * @return {object} The item object.
 */
function get(arg) {
  // Implementation that handles both cases
}

গুগল শিটসে কাস্টম ফাংশন

গুগল শিটসের জন্য কাস্টম ফাংশন লেখার সময়, স্প্রেডশিটের অটোকমপ্লিট ও ফর্মুলা হেল্পারে সেটি দেখানোর জন্য আপনাকে অবশ্যই @customfunction ট্যাগটি ব্যবহার করতে হবে।

গুগল শিটসে আপনার কাস্টম ফাংশন ব্যবহার করার সময় ব্যবহারকারীরা যে সহায়ক টেক্সট দেখতে পান, তার উৎস হলো JSDoc। JSDoc ছাড়া, ব্যবহারকারীরা শুধুমাত্র ফাংশনের নামটি দেখতে পেতেন, ফলে ফাংশনটি কী কাজ করে বা এর জন্য কী কী প্যারামিটার প্রয়োজন, তা বোঝা কঠিন হয়ে পড়ত।

সমর্থিত ট্যাগ এবং UI সীমাবদ্ধতা

যদিও অ্যাপস স্ক্রিপ্ট বেশিরভাগ স্ট্যান্ডার্ড JSDoc ট্যাগ পার্স করতে পারে, কাস্টম ফাংশনের জন্য গুগল শিটস UI-এর কিছু নির্দিষ্ট আচরণ এবং সীমাবদ্ধতা রয়েছে:

• @customfunction : ফাংশনটি শীটস ফর্মুলা তালিকায় দেখানোর জন্য এটি আবশ্যক।
• @param : নাম এবং বিবরণ শীটস ফর্মুলা হেল্পারে প্রদর্শিত হয়।
• @return : @return ট্যাগে প্রদত্ত বিবরণ শীটস ফর্মুলা হেল্পারে প্রদর্শিত হয় না ।
• ঐচ্ছিক প্যারামিটার : ঐচ্ছিক প্যারামিটারের জন্য ব্যবহৃত সাধারণ JSDoc সিনট্যাক্স (যেমন, [name] বা name= ) Sheets UI দ্বারা স্বীকৃত নয়। ফর্মুলা হেল্পারে সমস্ত প্যারামিটার আবশ্যক হিসেবে প্রদর্শিত হবে।
• ডিফল্ট মান : ডিফল্ট প্যারামিটার মান (যেমন, [name=Value] ) শীটস UI-তে সমর্থিত নয়।
• ফরম্যাটিং : আপনার বিবরণে HTML ট্যাগ এবং সাধারণ টেক্সট লাইন ব্রেক সমর্থিত নয়। শীটস UI বিবরণটিকে একটি একক টেক্সট ব্লক হিসেবে প্রদর্শন করে এবং বেশিরভাগ HTML বাদ দিয়ে দেয়।

গুগল শিটসের উদাহরণ

/**
 * Calculates a discount.
 *
 * @param {number} price The original price.
 * @param {number} percent The discount percentage (e.g., 0.1 for 10%).
 * @return {number} The price after discount.
 * @customfunction
 */
function calculateDiscount(price, percent) {
  return price * (1 - percent);
}

ব্যবহারকারীরা গুগল শিটসে যা দেখেন

যখন কোনো ব্যবহারকারী একটি সেলে =CALCULATEDISCOUNT( টাইপ করেন, তখন গুগল শিটস নিম্নলিখিত হেল্পার বক্সটি প্রদর্শন করে:

গণনাকৃত ছাড়

ছাড় গণনা করে।

মূল্য : আসল মূল্য।

শতাংশ : ছাড়ের হার (যেমন, ১০%-এর জন্য ০.১)।

লক্ষ্য করুন যে, প্যারামিটারগুলোর বিবরণ সরাসরি আপনার JSDoc-এর @param ট্যাগগুলো থেকে নেওয়া হয়েছে।

স্ক্রিপ্ট-স্তরের টীকা

অ্যাপস স্ক্রিপ্ট পুরো স্ক্রিপ্টের সেটিংস নিয়ন্ত্রণ করতে স্বতন্ত্র JSDoc ট্যাগ ব্যবহার করে। এগুলো সাধারণত একটি স্ক্রিপ্ট ফাইলের শীর্ষে রাখা হয়।

অনুমোদন ট্যাগ