Question

我从未真正编写过javadocs，并开始为工作中的本地应用程序编写它们。其中大多数是Java servlet。我担心我的描述性/复杂程度太高了。

即使我对浏览器发送的所有表单类型感到困惑，所以我试图将它们包含在javadoc中。

所有servlet都有以下自定义标记：

    tag form.Type:a:"Form types sent from browser:"

以下是一个processRequest的javadoc示例：

/**
 * Handles requests from browser.
 * 
 * @param request
 * @param response
 * @throws ServletException
 * @throws IOException
 * @form.Type initial: Calls {@link org.bcso.com.appearancerequest.html.NotifierHTML#getHTML} if
 * credentials are valid<br>
 * submitRequest: Calls {@see #submitRequest(HttpServletRequest request)}<br>
 * afterEdit: Calls {@link org.bcso.com.appearancerequest.html.AdminHTML#getHTML()}<br>
 * getAdmin: Calls {@link org.bcso.com.appearancerequest.html.AdminHTML#getHTML()}<br>
 * getDeputyAdmin: Calls {@link org.bcso.com.appearancerequest.html.DepAdminHTML#getHTML()}<br>
 * deleteDeputy: Calls {@see deleteDeputy(HttpServletRequest request)}<br>
 * saveOrUpdateDeputy: Calls {@see addOrUpdateDeputy(HttpServletRequest request)}<br>
 * getCourtAdmin: Calls {@link org.bcso.com.appearancerequest.html.CourtAdminHTML#getHTML()}<br>
 * saveOrUpdateCourt: Calls {@see addOrUpdateCourt(HttpServletRequest request)}<br>
 * deleteCourt: Calls {@see deleteCourt(HttpServletRequest request)}<br>
 * getReports: Calls the {@link org.bcso.com.appearancerequest.html.ReportsHTML#getHTML()}<br>
 * reportByDate: Calls {@see getReportByDate(HttpServletRequest request)} <br>
 * reportByDeputy: Calls {@see getReportByDeputy(HttpServletRequest request)}<br>
 * reportByRequestor: Calls {@see getReportByRequestor(HttpServletRequest request)}<br>
 * saveNoShow: Saves data concerning a deputy who no-shows via {@link org.bcso.com.appearancerequest.util.DatabaseUtil#saveNoShow(javax.servlet.http.HttpServletRequest)} 
 * and generates an email via {@see sendNoShow(int deputyId, int notificationId)} to admin.<br>
 * reviewLogin: Calls {@see #reviewerLogin(Map user)}<br>
 *
 */

我这样做了吗？还有更好的方法吗？

Answer 1

我认为这个数量的文档不算太大。您需要考虑其格式，因为此格式与How to Write Doc Comments for the Javadoc Tool中的示例非常不同。

不清楚submitRequest和down中的变量属于请求，还是应该填入响应。您的文档中的{@link}和{@see}也会产生相同的效果。我不确定你为什么在某些地方使用一个，而在另一个地方使用其他地方。

只是我的观察。

使用@link和@see与Javadocs

1 个答案: