1   /*
2    * SPDX-FileCopyrightText: none
3    * SPDX-License-Identifier: CC0-1.0
4    */
5   
6   package gov.nist.secauto.metaschema.core.model;
7   
8   import gov.nist.secauto.metaschema.core.datatype.markup.MarkupLine;
9   
10  import edu.umd.cs.findbugs.annotations.Nullable;
11  
12  /**
13   * Represents a model element that has a formal name and description.
14   * <p>
15   * This interface provides access to human-readable documentation properties
16   * that describe the purpose and usage of a model element.
17   */
18  public interface IDescribable {
19    /**
20     * The formal display name.
21     *
22     * @return the formal name or {@code null} if not defined
23     */
24    // from INamedModelElement
25    @Nullable
26    String getFormalName();
27  
28    /**
29     * Get the text that describes the basic use of the element.
30     *
31     * @return a line of markup text or {@code null} if not defined
32     */
33    // from INamedModelElement
34    @Nullable
35    MarkupLine getDescription();
36  
37    /**
38     * The resolved formal display name, which allows an instance to override a
39     * definition's name.
40     *
41     * @return the formal name or {@code null} if not defined
42     */
43    // from INamedModelElement
44    @Nullable
45    default String getEffectiveFormalName() {
46      return getFormalName();
47    }
48  
49    /**
50     * Get the text that describes the basic use of the element, which allows an
51     * instance to override a definition's description.
52     *
53     * @return a line of markup text or {@code null} if not defined
54     */
55    // from INamedModelElement
56    @Nullable
57    default MarkupLine getEffectiveDescription() {
58      return getDescription();
59    }
60  }