系统学习magento二次开发，推荐小册：《Magento中文全栈二次开发 》
本小册面向Magento2以上版本，书代码及示例兼容magento2.0-2.4版本。涵盖了magento前端开发，后端开发，magento2主题,magento2重写,magento2 layout,magento2控制器,magento2 block等相关内容,带领您成为magento开发技术专家。
以下是Magento 2中的文档块标准：
文档块应该放在一个函数或方法的前面，用于描述该函数或方法的作用和参数。
文档块应该以“/**”开头，以“/”结尾，并在“”后留出一个空格。
文档块应该包括一个简要描述、一个详细描述和一个参数列表。
每个参数应该在一个新行中描述，包括参数的名称、类型和描述。
对于返回值，应该包括一个描述和返回值类型。
如果有任何抛出异常的情况，应该在文档块中描述它们。
对于私有方法或属性，应该在文档块中标记为“@private”。
对于受保护的方法或属性，应该在文档块中标记为“@protected”。
以下是一个Magento 2中的文档块示例：
/**
* A class representing a product.
*
* @class Product
*/
class Product {
/**
* Creates a new Product.
*
* @constructor
* @param {string} name - The name of the product.
* @param {number} price - The price of the product.
* @param {string} description - A description of the product.
*/
constructor(name, price, description) {
this.name = name;
this.price = price;
this.description = description;
}
/**
* Calculates the total price of the product including tax.
*
* @returns {number} - The total price including tax.
* @throws {Error} - If the price is not a number.
*/
calculateTotalPrice() {
if (typeof this.price !== 'number') {
throw new Error('Price must be a number');
}
const tax = this.price * 0.1;
const totalPrice = this.price + tax;
return totalPrice;
}
}
/**
* A function that adds two numbers.
*
* @function add
* @param {number} a - The first number to add.
* @param {number} b - The second number to add.
* @returns {number} - The sum of the two numbers.
*/
function add(a, b) {
return a + b;
}在这个示例中，我们使用文档块来描述一个名为“Product”的类和一个名为“add”的函数。文档块包括一个简要描述、一个详细描述和一个参数列表。每个参数在一个新行中描述，包括参数的名称、类型和描述。我们还在文档块中包括了一个返回值描述和返回值类型。在calculateTotalPrice方法中，我们还使用了@throws标记来描述可能抛出的异常。