001/*
002 * SPDX-FileCopyrightText: none
003 * SPDX-License-Identifier: CC0-1.0
004 */
005
006package dev.metaschema.core.model;
007
008import dev.metaschema.core.datatype.markup.MarkupLine;
009import edu.umd.cs.findbugs.annotations.Nullable;
010
011/**
012 * Represents a model element that has a formal name and description.
013 * <p>
014 * This interface provides access to human-readable documentation properties
015 * that describe the purpose and usage of a model element.
016 */
017public interface IDescribable {
018  /**
019   * The formal display name.
020   *
021   * @return the formal name or {@code null} if not defined
022   */
023  // from INamedModelElement
024  @Nullable
025  String getFormalName();
026
027  /**
028   * Get the text that describes the basic use of the element.
029   *
030   * @return a line of markup text or {@code null} if not defined
031   */
032  // from INamedModelElement
033  @Nullable
034  MarkupLine getDescription();
035
036  /**
037   * The resolved formal display name, which allows an instance to override a
038   * definition's name.
039   *
040   * @return the formal name or {@code null} if not defined
041   */
042  // from INamedModelElement
043  @Nullable
044  default String getEffectiveFormalName() {
045    return getFormalName();
046  }
047
048  /**
049   * Get the text that describes the basic use of the element, which allows an
050   * instance to override a definition's description.
051   *
052   * @return a line of markup text or {@code null} if not defined
053   */
054  // from INamedModelElement
055  @Nullable
056  default MarkupLine getEffectiveDescription() {
057    return getDescription();
058  }
059}