具有相同目标的服务和 DAO 层类的 javadoc

Question

我正在为我的 jsp 网络应用程序编写 javadoc。所以我有一个名为 AcceptOrder 的类(根据命令模式创建并位于服务层)。此类包含方法 execute 并从 DAO 层调用方法 acceptOrder。类位于服务层。

/**

* 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);
}

}

此外，我在驱动程序 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);
        }
    }

所以问题是:我应该为它写什么 javadoc，我的命令方法执行的 javadoc 是否正确？两种方法的描述中应该写什么。似乎他们的描述是相同的 - 接受客户订单。

Answer 1

我认为您应该更好地解释方法的作用、引发异常的情况、返回值、实际返回的内容以及原因。如何调用这个方法，例子。您可以在类级别解释的常见用法、使用的依赖项、一般工作流程、验证、建模。