[英]javadoc for service and DAO layer classes with same targets
I'm writing javadoc for my jsp web application. 我正在为我的jsp web应用程序编写javadoc。 So i have a class (created according to Command pattern and located in service layer) called AcceptOrder.
所以我有一个名为AcceptOrder的类(根据Command模式创建并位于服务层中)。 This class contains method execute and it calls method acceptOrder from DAO layer.
该类包含方法execute,它从DAO层调用方法acceptOrder。 Class is located in service layer.
类位于服务层。
/**
* Class allows customer order (which was assigned by dispatcher) be accepted by driver.
*
*
*/
public class AcceptOrder implements Command {
private static final String USER_ATTRIBUTE = "user";
private static final String ORDER_ID_ATTRIBUTE = "order_id";
private static final String DAO_COMMAND_EXCEPTION_MESSAGE = "Exception on executing DAO command";
private static final String WRONG_ORDER_ID_EXCEPTION_MESSAGE = "Wrong order ID";
/** {@inheritDoc}
* <p> Accepts user order, which was assigned by dispatcher.
* @param request request object
* @param response response object
*/
@Override
public String execute(HttpServletRequest request, HttpServletResponse response) throws CommandException {
DriverDao driverDao = MySqlDaoFactory.getInstance().getDriverDao();
try {
User user = (User) request.getSession().getAttribute(USER_ATTRIBUTE);
int userId = user.getId();
int orderId = Integer.valueOf(request.getParameter(ORDER_ID_ATTRIBUTE));
driverDao.acceptOrder(orderId, userId);
} catch (DaoException e) {
throw new CommandException(DAO_COMMAND_EXCEPTION_MESSAGE, e);
} catch (NumberFormatException e) {
throw new CommandException(WRONG_ORDER_ID_EXCEPTION_MESSAGE, e);
}
return PageManager.getInstance().generatePageRequest(CommandName.SHOW_DRIVER_ORDER);
}
}
Aslo i have a method in driver DAO class (in DAO layer) called acceptOrder which connects to the database and apply some changes according to parameters. 我在驱动程序DAO类(在DAO层中)中有一个名为acceptOrder的方法,它连接到数据库并根据参数应用一些更改。
@Override
public void acceptOrder(int orderId, int userId) throws DaoException {
ConnectionPool connectionPool = null;
Connection connection = null;
PreparedStatement preparedStatement = null;
ResultSet result = null;
try {
connectionPool = ConnectionPool.getInstance();
connection = connectionPool.takeConnection();
preparedStatement = connection.prepareStatement(SQL_ACCEPT_ORDER);
preparedStatement.setInt(1, userId);
preparedStatement.setInt(2, orderId);
preparedStatement.executeUpdate();
} catch (SQLException e) {
throw new DaoException(STATEMENT_EXCEPTION_MESSAGE, e);
} catch (ConnectionPoolException e) {
throw new DaoException(CONNECTION_POOL_EXCEPTION_MESSAGE, e);
} finally {
connectionPool.closeConnection(connection, preparedStatement, result);
}
}
So the question is : What javadoc should i write for it and is my javadoc for command method execute is correct? 所以问题是 :我应该为它编写什么javadoc并且我的命令方法执行的javadoc是否正确? What should be written in the description of both methods.
在两种方法的描述中应该写什么。 Seems like their descriptions are the same- accept customer order.
似乎他们的描述是相同的 - 接受客户订单。
I think you should explain better what is the method doing, cases when exception is thrown, returned values, what is actually returned and why. 我认为你应该更好地解释方法在做什么,抛出异常的情况,返回的值,实际返回的内容以及原因。 How to call this method, examples.
如何调用此方法,示例。 A common usage, dependencies used, general workflow, validation, modeling you can explain at the class level.
您可以在课程级别解释常见用法,使用的依赖关系,一般工作流程,验证,建模。
I try to follow the rules below. 我尝试遵循以下规则。
null
handling. null
处理。 Is it accepted as the parameter value? null
? null
吗? If yes, under what circumstances? final
, right)? final
,right)? If yes, should subclasses obey any specific rules? And again, always try to think what information you would expect from an external library. 再一次,总是试着想一想你对外部库有什么样的信息。 I use Java SDK and Java EE javadoc a lot.
我经常使用Java SDK和Java EE javadoc。 Some parts of it are great.
它的某些部分很棒。 From others I would expect information like if I can use an object from multiple threads or not but there is no single word about it and I have to refer to sources (and there will never be guarantee that my findings will be correct).
从其他人那里我会期待信息,比如我是否可以使用来自多个线程的对象,但是没有关于它的单词,我必须引用来源(并且永远不能保证我的发现是正确的)。
On the other hand think also if you should write a javadoc comment at all. 另一方面,也要考虑是否应该写一个javadoc注释。 Is it worth it?
这值得么? Will you have external clients of your API (especially without access to your source code)?
您是否拥有API的外部客户端(特别是无法访问您的源代码)? If you do, you probably should also write a reference manual .
如果你这样做,你可能也应该写一本参考手册 。 If you have a small application and a small team, it might be easier to just skim the short method body.
如果你有一个小应用程序和一个小团队,可能更容易浏览短方法体。
Note that I am not saying you shouldn't write javadoc at all. 请注意,我并不是说你根本不应该写javadoc。 I am trying to say that javadoc is a tool with a specific purpose.
我想说javadoc是一个具有特定目的的工具。 Think if writing a specific snippet of javadoc will help you to fulfill it.
想一想,如果编写一个特定的javadoc片段将帮助您实现它。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.