第一章 JAVA基础知识系列 -- 第一节 JAVADOC 常用注释语法
2019-05-22 12:54
459 查看
版权声明:本文为博主原创文章,遵循 CC 4.0 by-sa 版权协议,转载请附上原文出处链接和本声明。
本文链接:https://blog.csdn.net/tysite/article/details/90440181
JAVADOC 常用注释语法
参考文献: https://www.geek-share.com/detail/2659195941.html
javadoc是Sun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。
使用Gradle 管理的SpringBoot项目,可以通过 java 插件提供的
javadoc任务生成Java doc文档,命令如下
./gradlew javadoc
javadoc 常用标记如下表所示
JavaDoc 标 记 | 解释 |
---|---|
@author | 指定作者信息 |
@version | 指定当前版本信息 |
@since | 指定最早出现在哪个版本 |
@see | 生成参考其他的JavaDoc文档的连接 |
@link | 生成参考其他的JavaDoc文档,它和@see标记的区别在于,@link标记能够嵌入到注释语句中,为注释语句中的特殊词汇生成连接。 eg.{@linkHello} |
@deprecated | 用来注明被注释的类、变量或方法已经不提倡使用,在将来的版本中有可能被废弃 |
@param | 描述方法的参数 |
@return | 描述方法的返回值 |
@throws | 描述方法抛出的异常,指明抛出异常的条件 |
注意:
- javadoc 针对
public
类生成注释文档 - javadoc 只能在
public
、protected
修饰的方法或者属性之上 - javadoc 要仅靠在类、属性、方法之前
参考spring-webmvc 核心类DispatcherServlet 整理javadoc使用规范如下
按照代码从上至下简要说明
- 顶部使用 多行注释
/*
*/
语法填写LICENSE
信息 ,私有代码不加该内容 - 类所属包路径
- 类引入的资源
- (重点)类描述信息,用于注释类的 功能、作者、版本等信息
- 属性描述信息,用于注释属性的重要描述
- 构造方法描述信息,用于描述构造方法的用法意义
- 方法描述信息,用于描述方法的功能、传入参数@param,返回结果@return
DispatcherServlet 部分代码示例如下
/* * Copyright 2002-2018 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.springframework.web.servlet; import java.io.IOException; import java.util.ArrayList; 省略部分代码 import org.springframework.web.util.NestedServletException; import org.springframework.web.util.WebUtils; /** * Central dispatcher for HTTP request handlers/controllers, e.g. for web UI controllers * or HTTP-based remote service exporters. Dispatches to registered handlers for processing * a web request, providing convenient mapping and exception handling facilities. * * <p>This servlet is very flexible: It can be used with just about any workflow, with the * installation of the appropriate adapter classes. It offers the following functionality * that distinguishes it from other request-driven web MVC frameworks: * * <ul> * <li>It is based around a JavaBeans configuration mechanism. * * <li>It can use any {@link HandlerMapping} implementation - pre-built or provided as part * of an application - to control the routing of requests to handler objects. Default is * {@link org.springframework.web.servlet.handler.BeanNameUrlHandlerMapping} and * {@link org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping}. ……省略部分代码 * @author Rod Johnson * @author Juergen Hoeller * @author Rob Harrop * @author Chris Beams * @author Rossen Stoyanchev * @see org.springframework.web.HttpRequestHandler * @see org.springframework.web.servlet.mvc.Controller * @see org.springframework.web.context.ContextLoaderListener */ @SuppressWarnings("serial") public class DispatcherServlet extends FrameworkServlet { /** Well-known name for the MultipartResolver object in the bean factory for this namespace. */ public static final String MULTIPART_RESOLVER_BEAN_NAME = "multipartResolver"; /** Well-known name for the LocaleResolver object in the bean factory for this namespace. */ public static final String LOCALE_RESOLVER_BEAN_NAME = "localeResolver"; ……省略部分代码 /** List of ViewResolvers used by this servlet. */ @Nullable private List<ViewResolver> viewResolvers; /** * Create a new {@code DispatcherServlet} that will create its own internal web * application context based on defaults and values provided through servlet * init-params. Typically used in Servlet 2.5 or earlier environments, where the only * option for servlet registration is through {@code web.xml} which requires the use * of a no-arg constructor. * <p>Calling {@link #setContextConfigLocation} (init-param 'contextConfigLocation') * will dictate which XML files will be loaded by the * {@linkplain #DEFAULT_CONTEXT_CLASS default XmlWebApplicationContext} * <p>Calling {@link #setContextClass} (init-param 'contextClass') overrides the * default {@code XmlWebApplicationContext} and allows for specifying an alternative class, * such as {@code AnnotationConfigWebApplicationContext}. * <p>Calling {@link #setContextInitializerClasses} (init-param 'contextInitializerClasses') * indicates which {@code ApplicationContextInitializer} classes should be used to * further configure the internal application context prior to refresh(). * @see #DispatcherServlet(WebApplicationContext) */ public DispatcherServlet() { super(); setDispatchOptionsRequest(true); } /** * Create a new {@code DispatcherServlet} with the given web application context. This * constructor is useful in Servlet 3.0+ environments where instance-based registration * of servlets is possible through the {@link ServletContext#addServlet} API. * <p>Using this constructor indicates that the following properties / init-params * will be ignored: * <ul> * <li>{@link #setContextClass(Class)} / 'contextClass'</li> * <li>{@link #setContextConfigLocation(String)} / 'contextConfigLocation'</li> * <li>{@link #setContextAttribute(String)} / 'contextAttribute'</li> * <li>{@link #setNamespace(String)} / 'namespace'</li> * </ul> * <p>The given web application context may or may not yet be {@linkplain * ConfigurableApplicationContext#refresh() refreshed}. If it has <strong>not</strong> * already been refreshed (the recommended approach), then the following will occur: * <ul> * <li>If the given context does not already have a {@linkplain * ConfigurableApplicationContext#setParent parent}, the root application context * will be set as the parent.</li> * <li>If the given context has not already been assigned an {@linkplain * ConfigurableApplicationContext#setId id}, one will be assigned to it</li> * <li>{@code ServletContext} and {@code ServletConfig} objects will be delegated to * the application context</li> * <li>{@link #postProcessWebApplicationContext} will be called</li> * <li>Any {@code ApplicationContextInitializer}s specified through the * "contextInitializerClasses" init-param or through the {@link * #setContextInitializers} property will be applied.</li> * <li>{@link ConfigurableApplicationContext#refresh refresh()} will be called if the * context implements {@link ConfigurableApplicationContext}</li> * </ul> * If the context has already been refreshed, none of the above will occur, under the * assumption that the user has performed these actions (or not) per their specific * needs. * <p>See {@link org.springframework.web.WebApplicationInitializer} for usage examples. * @param webApplicationContext the context to use * @see #initWebApplicationContext * @see #configureAndRefreshWebApplicationContext * @see org.springframework.web.WebApplicationInitializer */ public DispatcherServlet(WebApplicationContext webApplicationContext) { super(webApplicationContext); setDispatchOptionsRequest(true); } ……省略部分代码 /** * Initialize the strategy objects that this servlet uses. * <p>May be overridden in subclasses in order to initialize further strategy objects. */ protected void initStrategies(ApplicationContext context) { initMultipartResolver(context); initLocaleResolver(context); initThemeResolver(context); initHandlerMappings(context); initHandlerAdapters(context); initHandlerExceptionResolvers(context); initRequestToViewNameTranslator(context); initViewResolvers(context); initFlashMapManager(context); } /** * Initialize the MultipartResolver used by this class. * <p>If no bean is defined with the given name in the BeanFactory for this namespace, * no multipart handling is provided. */ private void initMultipartResolver(ApplicationContext context) { try { this.multipartResolver = context.getBean(MULTIPART_RESOLVER_BEAN_NAME, MultipartResolver.class); if (logger.isTraceEnabled()) { logger.trace("Detected " + this.multipartResolver); } else if (logger.isDebugEnabled()) { logger.debug("Detected " + this.multipartResolver.getClass().getSimpleName()); } } catch (NoSuchBeanDefinitionException ex) { // Default is no multipart resolver. this.multipartResolver = null; if (logger.isTraceEnabled()) { logger.trace("No MultipartResolver '" + MULTIPART_RESOLVER_BEAN_NAME + "' declared"); } } } ……省略部分代码 /** * Build a LocaleContext for the given request, exposing the request's primary locale as current locale. * <p>The default implementation uses the dispatcher's LocaleResolver to obtain the current locale, * which might change during a request. * @param request current HTTP request * @return the corresponding LocaleContext */ @Override protected LocaleContext buildLocaleContext(final HttpServletRequest request) { LocaleResolver lr = this.localeResolver; if (lr instanceof LocaleContextResolver) { return ((LocaleContextResolver) lr).resolveLocaleContext(request); } else { return () -> (lr != null ? lr.resolveLocale(request) : request.getLocale()); } } ……省略部分代码 private static String getRequestUri(HttpServletRequest request) { String uri = (String) request.getAttribute(WebUtils.INCLUDE_REQUEST_URI_ATTRIBUTE); if (uri == null) { uri = request.getRequestURI(); } return uri; } }
相关文章推荐
- 第一章 JAVA基础知识系列 -- 第二节 注解概念及应用
- javaSE_8系列博客——Java语言的特性(二)--高级语言的基础知识(2)-- 变量和常用数据类型
- 第一章 JAVA基础知识系列 -- 第三节 正则表达式
- java基础知识记录--基本语法 (摘自张孝祥整理java面试题)
- Java私塾跟我学系列――JAVA篇 第二章 基础语法00
- Java基础知识强化之网络编程笔记21:Android网络通信之 Android常用OAuth登录(获取令牌信息)
- Java基础知识回顾-5 常用基础类
- Java基础系列之Java语法
- Java基础知识强化之网络编程笔记20:Android网络通信之 Android常用OAuth登录和分享
- css3基础知识第一章语法
- Java私塾跟我学系列――JAVA篇 第二章 基础语法
- java基础知识字节位、javadoc文件的生产、获取键盘输入、方法和变量静态情况
- JavaSE(1):java基础知识及基础语法
- day01(计算机基本知识+JAVA基础知识+环境变量的配置+标识符命名规则+注释的分类)
- Java常用的设计模式08:框架基础知识
- java基础知识--接口语法细节
- 数据库知识整理:基础语法 第一章
- Java基础知识之常用类库(1)
- Java私塾跟我学系列――JAVA篇 第二章 基础语法
- Java私塾跟我学系列――JAVA篇 第二章 基础语法