Page MenuHomePhabricator

Docs
Updated 1,851 Days AgoPublic

Doc Syntax

/* COMMENTS ARE IMPORTANT, READ THEM. */

type Something: int; [[Use to describe Somethings]] // Simple type definition

// external structs - defined in the system and not to be generated in C
struct @extern foo {
    // @Evas.Bar references Evas.Bar
    [[This structure is used for good.

      It can also be used for evil if you do xyz.

      See also @Evas.Bar.

      Note: this is a note.

      Warning: this is a warning. This is in $monospace.
    ]]
    x: Something; [[The x value, see @Something for possible values]]
    y: float; [[The y value]]
}

class Elm.Button (Elm.Layout, Evas.Interface.Clickable) {
    [[A class for creating UI buttons.]]
    methods {
        @property some_part_text {
            [[Doc for the property in general. Both set and get.

              You can refer to other methods within class like @.foo or @Elm.Button.foo.
              To refer to methods in other classes or non-methods, you need full namespace.
            ]]
            set {
                [[Docs - extra for set (optional)]]
            }
            get {
                [[Docs -extra for get (optional)]]
            }

            keys {
                part: const(char)*; [[Extra params for both]]
            }

            values {
                text: char*; [[The text]]
            }
        }
        foo {
        }

    implements {
        Elm.Widget.activate; [[Some extra docs about this applies for this widget]]
        Evas.Smart.add;
    }
    events {
        some_private_event @private: int; [[Some docs about this event]]
    }
}
const approximate_pi: float = 3.14; [[Docs about this type]]

/* Globals */
var some_global_var: int; [[And this type]]

enum Foo {
    first_item, [[docs about this one]] 
    second_item
}

Comments

  • "Story" docs will be in the wiki.
  • Generators will have to generate docs for IDEs (so they'll show in doc previews).
  • References like @Foo.first_item will be translated by the generator according to the language, for example to FOO_FIRST_ITEM for C.
  • References are only allowed to *known* Eolian types. Referencing an unknown type is an error.
  • We'll use the class, and the structure of the Eolian file to generate the structure of the docs including sections and inheritance.
Last Author
q66
Last Edited
Jul 14 2015, 2:24 AM
Projects
None
Subscribers
None