+ Reply to Thread
Results 1 to 4 of 4

Thread: Coming soon: teaDoc

  1. #1
    Plane Touched Verea's Avatar
    Join Date
    Feb 2011
    Location
    Netherlands
    Posts
    200

    Default Coming soon: teaDoc

    Salutations,

    No developer enjoys writing documentation, am I right? Coding and scripting is fun and productive, but then documenting those functions and library calls just gets really annoying and bothersome. Especially the start of it! Luckily, there will be a solution to this bothersome task soon, or at least something to help make it easier.

    TeaDoc is part of the suite that Tea Club offers to their add-on developers, but also to the general public - whether you use our services or not. TeaDoc automatically reads all your LUA files in a given directory (recursively) and checks the comments for function documentation.

    Maybe an example is easier to understand:
    Code:
    -- myFunction()
    --  Prints 'Hello, name' to the console.
    --usage: myFunction(name)
    --param: <string> name A name to print.
    --return: <string> The string that was printed.
    local function myFunction(name)
        local s = "Hello, " .. name
        print(s)
        return s
    end
    If we'd now run the following on the command line:
    $ tdoc myFunction.lua -o function.html

    We'd get the following file:
    Code:
    <html>
        <head><title>myFunction.lua</title></head>
    
        <body>
           <h1>myFunction.lua</h1>
           <h2>myFunction()</h2>
           <p>Prints 'Hello, name' to the console.</p>
           <p><b>usage:</b> myFunction(name)</p>
           
           <h4>Parameters</h4>
           <ul>
             <li>&gt;string&lt;<b>name</b> A name to print.</li>
           </ul>
    
           <h4>Return values</h4>
           <ul>
              <li>&gt;string&lt; The string that was printed.</li>
           </ul>
        </body>
    </html>
    Which would give you a nice, bare bone documentation page to begin working with. A complete feature list:
    • Fully supports namespaces (Tea.) (Tea.Addon.) etc.
    • Allows customized HTML templates to offer more direct control to the output.
    • Full support for Rift UI primitives as types (RiftSlider etc)
    • Can output source-code to HTML with syntax highlighting.
    • Support for class documentation (granted that Tea.class is used from libTea).
    • Can be configured to support own 'types'.
    • Can document anything ranging from files itself to namespaces, variables, classes, functions and UI Objects.

    teaDoc is a work in progress, a beta will be available when it's stable enough.

    Love,
    Verea

    Also FAQ:
    In what language is teaDoc written?
    teaDoc is written in the D Programming Language, version 2.0, which means that it's compiled to native binary code for maximum performance.

    Does teaDoc only export to HTML?
    No, teaDoc can also export to XML and JSON files.

    Is there a complete reference on the syntax teaDoc looks for?
    Not yet, but it will be long available before teaDoc itself is released so you get time to prepare your comments.

    Can I exclude functions from being documented?
    You can add $tea.exclude to the comment, position is irrelevant.

    Is it possible to let teaDoc write a list of all present functions in a given namespace?
    Yes, and it can print them in a separate HTML file too.

    How does teaDoc resolve URLs to other functions that are referenced, files and classes?
    It uses a little database for this. This will be either in SQLite or a XML file.
    This will also speed up edits and changes to your files, by not having to reindex the entire file.

    Is teaDoc open-source software?
    Like all my software, teaDoc is licensed under the MIT License.

    What platforms does teaDoc run on?
    It runs on Windows, Linux and Mac OS X.
    Last edited by Verea; 03-12-2012 at 07:58 AM. Reason: FAQ
    Verae, level 60 Cleric @ Blightweald, Guild Master of Tea Club
    I want to fly like an eagle, to the sea.
    I want to fly like an eagle, let my spirit carry me.

  2. #2
    Plane Walker Imhothar's Avatar
    Join Date
    Feb 2012
    Posts
    439

    Default

    The idea is good, but I hope you aren't re-inventing the wheel: LuaDoc

  3. #3
    Plane Touched Verea's Avatar
    Join Date
    Feb 2011
    Location
    Netherlands
    Posts
    200

    Default

    No, this one is more specialized towards libTea and Rift's API in general. It can document events and the likes, too.
    Verae, level 60 Cleric @ Blightweald, Guild Master of Tea Club
    I want to fly like an eagle, to the sea.
    I want to fly like an eagle, let my spirit carry me.

  4. #4
    Plane Walker Imhothar's Avatar
    Join Date
    Feb 2012
    Posts
    439

    Default

    Cool then. I once saw a perl script somewhere to make Doxygen accept Lua files, that was very interesting.

+ Reply to Thread

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts