001/*
002 * Copyright (c) 2012-2018 Institut National des Sciences Appliquées de Lyon (INSA Lyon) and others
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License 2.0 which is available at
006 * http://www.eclipse.org/legal/epl-2.0.
007 *
008 * SPDX-License-Identifier: EPL-2.0
009 */
010
011package org.eclipse.golo.doc;
012
013public interface DocumentationElement extends Comparable<DocumentationElement> {
014
015  /**
016   * The simple name of the element.
017   */
018  String name();
019
020  /**
021   * The documentation comment for the element.
022   */
023  String documentation();
024
025  /**
026   * Chech if this element has a documentation.
027   * <p>
028   * An element has a documentation if its {@link #documentation()} method returns a non null non empty (when trimmed)
029   * string.
030   */
031  default boolean hasDocumentation() {
032    String doc = documentation();
033    if (doc == null) {
034      return false;
035    }
036    doc = doc.trim();
037    return !doc.isEmpty();
038  }
039
040  /**
041   * The line where the element is defined.
042   */
043  int line();
044
045  /**
046   * The parent element.
047   * <p>
048   * For toplevel element, this is the module. For functions, it can be the augmentation. For union values, it is the
049   * union.
050   */
051  DocumentationElement parent();
052
053  /**
054   * A readable name for the kind of element.
055   */
056  String type();
057
058  /**
059   * The fully qualified named of the element.
060   * <p>
061   * Typically, the parent full name and the element name.
062   */
063  default String fullName() {
064    return parent().fullName() + "." + name();
065  }
066
067  /**
068   * A unique identifier for the element.
069   * <p>
070   * Can be used in html ID for instance.
071   */
072  default String id() {
073    if (parent() != null && !parent().id().isEmpty()) {
074      return parent().id() + '.' + name();
075    }
076    return name();
077  }
078
079  /**
080   * A readable representation of the element.
081   * <p>
082   * Typically the name, but can also contains argument names for functions for instance.
083   */
084  default String label() {
085    return name();
086  }
087
088  default int compareTo(DocumentationElement other) {
089    if (this == other) { return 0; }
090    if (other == null) { return 1; }
091    int c = label().compareToIgnoreCase(other.label());
092    if (c == 0) {
093      c = type().compareTo(other.type());
094    }
095    if (c == 0 && parent() != this) {
096      c = parent().compareTo(other.parent());
097    }
098    return c;
099  }
100}
101