2122

Committed 26 Mar 2026 06:40PM UTC coverage: 90.331% (+0.06%) from 90.271%

Build # 2122

Build Type

Pull #1480

github

Committed by

web-flow

Commit Message

Merge f1ba1864e into c987e5562

Pull Request Pull Request #1480: Comment Generator Enhancements

Coverage Stats

2416 of 3182 branches covered (75.93%)

166 of 178 new or added lines in 35 files covered. (93.26%)

5 existing lines in 3 files now uncovered.

11752 of 13010 relevant lines covered (90.33%)

0.9 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

31.25

/core/mybatis-generator-core/src/main/java/org/mybatis/generator/api/CommentGenerator.java

/*
 *    Copyright 2006-2026 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
 *
 *       https://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.mybatis.generator.api;

import java.util.Properties;
import java.util.Set;

import org.mybatis.generator.api.dom.java.CompilationUnit;
import org.mybatis.generator.api.dom.java.Field;
import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
import org.mybatis.generator.api.dom.java.InnerClass;
import org.mybatis.generator.api.dom.java.InnerEnum;
import org.mybatis.generator.api.dom.java.InnerRecord;
import org.mybatis.generator.api.dom.java.Method;
import org.mybatis.generator.api.dom.java.TopLevelClass;
import org.mybatis.generator.api.dom.kotlin.KotlinFile;
import org.mybatis.generator.api.dom.kotlin.KotlinFunction;
import org.mybatis.generator.api.dom.kotlin.KotlinProperty;
import org.mybatis.generator.api.dom.kotlin.KotlinType;
import org.mybatis.generator.api.dom.xml.XmlElement;

/**
 * Implementations of this interface are used to generate comments for the
 * various artifacts.
 *
 * @author Jeff Butler
 */
public interface CommentGenerator {

    /**
     * Adds properties for this instance from any properties configured in the
     * CommentGenerator configuration.
     *
     * <p>This method will be called before any of the other methods.
     *
     * @param properties
     *            All properties from the configuration
     */
    void addConfigurationProperties(Properties properties);

    /**
     * Adds a comment for a model class.  The Java code merger should
     * be notified not to delete the entire class in case any manual
     * changes have been made.  So this method will always use the
     * "do not delete" annotation.
     *
     * <p>Because of difficulties with the Java file merger, the default implementation
     * of this method should NOT add comments.  Comments should only be added if
     * specifically requested by the user (for example, by enabling table remark comments).
     *
     * @param topLevelClass
     *            the top level class
     * @param introspectedTable
     *            the introspected table
     */
    default void addModelClassComment(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) {}

    /**
     * Adds a comment for a model class.
     *
     * @param modelClass
     *            the generated KotlinType for the model
     * @param introspectedTable
     *            the introspected table
     */
    default void addModelClassComment(KotlinType modelClass, IntrospectedTable introspectedTable) {}

    /**
     * This method is called to add a file level comment to a generated java file. This method
     * could be used to add a general file comment (such as a copyright notice). However, note
     * that the Java file merge function may not preserve this comment. If you run
     * the generator repeatedly, you will only retain the comment from the initial run.
     *
     * <p>The default implementation does nothing.
     *
     * @param compilationUnit
     *            the compilation unit
     */
    default void addJavaFileComment(CompilationUnit compilationUnit) {}

    /**
     * This method should add a suitable comment as a child element of the specified xmlElement to warn users that the
     * element was generated and is subject to regeneration.
     *
     * @param xmlElement
     *            the xml element
     */
    default void addComment(XmlElement xmlElement) {}

    /**
     * This method is called to add a comment as the first child of the root element. This method
     * could be used to add a general file comment (such as a copyright notice). However, note
     * that the XML file merge function does not deal with this comment. If you run the generator
     * repeatedly, you will only retain the comment from the initial run.
     *
     * <p>The default implementation does nothing.
     *
     * @param rootElement
     *            the root element
     */
    default void addRootComment(XmlElement rootElement) {}

    /**
     * Adds a @Generated annotation to a method.
     *
     * @param method
     *            the method
     * @param introspectedTable
     *            the introspected table
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 1.3.6
     */
    default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
            Set<FullyQualifiedJavaType> imports) {}

    /**
     * Adds a @Generated annotation to a method.
     *
     * @param method
     *            the method
     * @param introspectedTable
     *            the introspected table
     * @param introspectedColumn
     *     the introspected column
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 1.3.6
     */
    default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
            IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}

    /**
     * Adds a @Generated annotation to a field.
     *
     * @param field
     *            the field
     * @param introspectedTable
     *            the introspected table
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 1.3.6
     */
    default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
            Set<FullyQualifiedJavaType> imports) {}

    /**
     * Adds a @Generated annotation to a field.
     *
     * @param field
     *            the field
     * @param introspectedTable
     *            the introspected table
     * @param introspectedColumn
     *            the introspected column
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 1.3.6
     */
    default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
            IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}

    /**
     * Adds a @Generated annotation to a class.
     *
     * @param innerClass
     *            the class
     * @param introspectedTable
     *            the introspected table
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 1.3.6
     */
    default void addClassAnnotation(InnerClass innerClass, IntrospectedTable introspectedTable,
            Set<FullyQualifiedJavaType> imports) {}

    /**
     * Adds a @Generated annotation to a class and marks it as do not delete. This means that the class should survive
     * a Java merge operation even if a newly generated method matches it (the new method will be discarded).
     *
     * @param innerClass the class
     * @param introspectedTable the introspected table
     * @param imports
     *     the comment generator may add a required imported type to this list
     */
    default void addClassAnnotationAndMarkAsDoNotDelete(InnerClass innerClass, IntrospectedTable introspectedTable,
                                                        Set<FullyQualifiedJavaType> imports) { }

    /**
     * Adds a @Generated annotation to a record.
     *
     * @param innerRecord
     *            the record
     * @param introspectedTable
     *            the introspected table
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 2.0.0
     */
    default void addRecordAnnotation(InnerRecord innerRecord, IntrospectedTable introspectedTable,
                                     Set<FullyQualifiedJavaType> imports) {}

    /**
     * Adds a @Generated annotation to an enum.
     *
     * @param innerEnum the enum
     * @param introspectedTable the introspected table
     * @param imports
     *     the comment generator may add a required imported type to this list
     *
     * @since 2.0.0
     */
    default void addEnumAnnotation(InnerEnum innerEnum, IntrospectedTable introspectedTable,
                                   Set<FullyQualifiedJavaType> imports) {}

    /**
     * This method is called to add a file level comment to a generated Kotlin file. This method
     * could be used to add a general file comment (such as a copyright notice).
     *
     * <p>The default implementation does nothing.
     *
     * @param kotlinFile
     *            the Kotlin file
     */
    default void addFileComment(KotlinFile kotlinFile) {}

    default void addGeneralFunctionComment(KotlinFunction kf, IntrospectedTable introspectedTable,
            Set<String> imports) {}

    default void addGeneralPropertyComment(KotlinProperty property, IntrospectedTable introspectedTable,
            Set<String> imports) {}
}

1	/*
2	* Copyright 2006-2026 the original author or authors.
3	*
4	* Licensed under the Apache License, Version 2.0 (the "License");
5	* you may not use this file except in compliance with the License.
6	* You may obtain a copy of the License at
7	*
8	* https://www.apache.org/licenses/LICENSE-2.0
9	*
10	* Unless required by applicable law or agreed to in writing, software
11	* distributed under the License is distributed on an "AS IS" BASIS,
12	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13	* See the License for the specific language governing permissions and
14	* limitations under the License.
15	*/
16	package org.mybatis.generator.api;
17
18	import java.util.Properties;
19	import java.util.Set;
20
21	import org.mybatis.generator.api.dom.java.CompilationUnit;
22	import org.mybatis.generator.api.dom.java.Field;
23	import org.mybatis.generator.api.dom.java.FullyQualifiedJavaType;
24	import org.mybatis.generator.api.dom.java.InnerClass;
25	import org.mybatis.generator.api.dom.java.InnerEnum;
26	import org.mybatis.generator.api.dom.java.InnerRecord;
27	import org.mybatis.generator.api.dom.java.Method;
28	import org.mybatis.generator.api.dom.java.TopLevelClass;
29	import org.mybatis.generator.api.dom.kotlin.KotlinFile;
30	import org.mybatis.generator.api.dom.kotlin.KotlinFunction;
31	import org.mybatis.generator.api.dom.kotlin.KotlinProperty;
32	import org.mybatis.generator.api.dom.kotlin.KotlinType;
33	import org.mybatis.generator.api.dom.xml.XmlElement;
34
35	/**
36	* Implementations of this interface are used to generate comments for the
37	* various artifacts.
38	*
39	* @author Jeff Butler
40	*/
41	public interface CommentGenerator {
42
43	/**
44	* Adds properties for this instance from any properties configured in the
45	* CommentGenerator configuration.
46	*
47	* <p>This method will be called before any of the other methods.
48	*
49	* @param properties
50	* All properties from the configuration
51	*/
52	void addConfigurationProperties(Properties properties);
53
54	/**
55	* Adds a comment for a model class. The Java code merger should
56	* be notified not to delete the entire class in case any manual
57	* changes have been made. So this method will always use the
58	* "do not delete" annotation.
59	*
60	* <p>Because of difficulties with the Java file merger, the default implementation
61	* of this method should NOT add comments. Comments should only be added if
62	* specifically requested by the user (for example, by enabling table remark comments).
63	*
64	* @param topLevelClass
65	* the top level class
66	* @param introspectedTable
67	* the introspected table
68	*/
NEW 69	default void addModelClassComment(TopLevelClass topLevelClass, IntrospectedTable introspectedTable) {}	×
70
71	/**
72	* Adds a comment for a model class.
73	*
74	* @param modelClass
75	* the generated KotlinType for the model
76	* @param introspectedTable
77	* the introspected table
78	*/
79	default void addModelClassComment(KotlinType modelClass, IntrospectedTable introspectedTable) {}	1✔
80
81	/**
82	* This method is called to add a file level comment to a generated java file. This method
83	* could be used to add a general file comment (such as a copyright notice). However, note
84	* that the Java file merge function may not preserve this comment. If you run
85	* the generator repeatedly, you will only retain the comment from the initial run.
86	*
87	* <p>The default implementation does nothing.
88	*
89	* @param compilationUnit
90	* the compilation unit
91	*/
92	default void addJavaFileComment(CompilationUnit compilationUnit) {}	1✔
93
94	/**
95	* This method should add a suitable comment as a child element of the specified xmlElement to warn users that the
96	* element was generated and is subject to regeneration.
97	*
98	* @param xmlElement
99	* the xml element
100	*/
101	default void addComment(XmlElement xmlElement) {}	×
102
103	/**
104	* This method is called to add a comment as the first child of the root element. This method
105	* could be used to add a general file comment (such as a copyright notice). However, note
106	* that the XML file merge function does not deal with this comment. If you run the generator
107	* repeatedly, you will only retain the comment from the initial run.
108	*
109	* <p>The default implementation does nothing.
110	*
111	* @param rootElement
112	* the root element
113	*/
114	default void addRootComment(XmlElement rootElement) {}	1✔
115
116	/**
117	* Adds a @Generated annotation to a method.
118	*
119	* @param method
120	* the method
121	* @param introspectedTable
122	* the introspected table
123	* @param imports
124	* the comment generator may add a required imported type to this list
125	*
126	* @since 1.3.6
127	*/
128	default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
129	Set<FullyQualifiedJavaType> imports) {}	×
130
131	/**
132	* Adds a @Generated annotation to a method.
133	*
134	* @param method
135	* the method
136	* @param introspectedTable
137	* the introspected table
138	* @param introspectedColumn
139	* the introspected column
140	* @param imports
141	* the comment generator may add a required imported type to this list
142	*
143	* @since 1.3.6
144	*/
145	default void addGeneralMethodAnnotation(Method method, IntrospectedTable introspectedTable,
146	IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}	×
147
148	/**
149	* Adds a @Generated annotation to a field.
150	*
151	* @param field
152	* the field
153	* @param introspectedTable
154	* the introspected table
155	* @param imports
156	* the comment generator may add a required imported type to this list
157	*
158	* @since 1.3.6
159	*/
160	default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
161	Set<FullyQualifiedJavaType> imports) {}	×
162
163	/**
164	* Adds a @Generated annotation to a field.
165	*
166	* @param field
167	* the field
168	* @param introspectedTable
169	* the introspected table
170	* @param introspectedColumn
171	* the introspected column
172	* @param imports
173	* the comment generator may add a required imported type to this list
174	*
175	* @since 1.3.6
176	*/
177	default void addFieldAnnotation(Field field, IntrospectedTable introspectedTable,
178	IntrospectedColumn introspectedColumn, Set<FullyQualifiedJavaType> imports) {}	×
179
180	/**
181	* Adds a @Generated annotation to a class.
182	*
183	* @param innerClass
184	* the class
185	* @param introspectedTable
186	* the introspected table
187	* @param imports
188	* the comment generator may add a required imported type to this list
189	*
190	* @since 1.3.6
191	*/
192	default void addClassAnnotation(InnerClass innerClass, IntrospectedTable introspectedTable,
193	Set<FullyQualifiedJavaType> imports) {}	×
194
195	/**
196	* Adds a @Generated annotation to a class and marks it as do not delete. This means that the class should survive
197	* a Java merge operation even if a newly generated method matches it (the new method will be discarded).
198	*
199	* @param innerClass the class
200	* @param introspectedTable the introspected table
201	* @param imports
202	* the comment generator may add a required imported type to this list
203	*/
204	default void addClassAnnotationAndMarkAsDoNotDelete(InnerClass innerClass, IntrospectedTable introspectedTable,
NEW 205	Set<FullyQualifiedJavaType> imports) { }	×
206
207	/**
208	* Adds a @Generated annotation to a record.
209	*
210	* @param innerRecord
211	* the record
212	* @param introspectedTable
213	* the introspected table
214	* @param imports
215	* the comment generator may add a required imported type to this list
216	*
217	* @since 2.0.0
218	*/
219	default void addRecordAnnotation(InnerRecord innerRecord, IntrospectedTable introspectedTable,
220	Set<FullyQualifiedJavaType> imports) {}	×
221
222	/**
223	* Adds a @Generated annotation to an enum.
224	*
225	* @param innerEnum the enum
226	* @param introspectedTable the introspected table
227	* @param imports
228	* the comment generator may add a required imported type to this list
229	*
230	* @since 2.0.0
231	*/
232	default void addEnumAnnotation(InnerEnum innerEnum, IntrospectedTable introspectedTable,
NEW 233	Set<FullyQualifiedJavaType> imports) {}	×
234
235	/**
236	* This method is called to add a file level comment to a generated Kotlin file. This method
237	* could be used to add a general file comment (such as a copyright notice).
238	*
239	* <p>The default implementation does nothing.
240	*
241	* @param kotlinFile
242	* the Kotlin file
243	*/
244	default void addFileComment(KotlinFile kotlinFile) {}	×
245
246	default void addGeneralFunctionComment(KotlinFunction kf, IntrospectedTable introspectedTable,
247	Set<String> imports) {}	1✔
248
249	default void addGeneralPropertyComment(KotlinProperty property, IntrospectedTable introspectedTable,
250	Set<String> imports) {}	1✔
251	}

mybatis / generator / 2122

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous