Re: documentation poll

From: mitchell <mforal.n....at.gmail.com>
Date: Sun, 13 Sep 2009 18:21:22 -0700 (PDT)

Robert,

> I've just been through the documents and have a few suggestions,
> sorry about being picky today, but I've finally had time to get around
> to really checkout TA.
>
> So...
>
> suggestion 1:
> the "Fields" section is not easy to look at. Especially for something
> like buffer. It's a horrible wall of text.
> Your function sections is great, changing "Fields" sections into
> something like the "Functions" section would be much nicer.
>
> suggestion 2:
> The "Fields" section should probably be below the "Functions" section.
> In general methods/functions are at a higher level (programatically
> speaking) than members/fields. Most use cases shouldn't even require
> manually changing fields (except for development of new functions).
>
> suggestion 3:
> In most doxygen and javadocs documentation there are links from
> modules/functions/fields to their corresponding source files.
>
> suggestion 4:
> For the suggestion 3 to make sense the source files should also be in
> the documentation under a files section

Thanks for your suggestions :) I'm just using the standard LuaDoc
templates, so I haven't bothered tweaking the presentation. I think
most Lua users are familiar with the layout anyway. As far as
including the source files, that would bloat up the downloadables. I
agree hard links would be nice, but I'm not willing to sacrifice a
small overall package size.

My chief concern was the contents of the documentation, not layout. I
just wanted to make sure it has everything necessary for Lua
scriptors.

Take care,
Received on Sun 13 Sep 2009 - 21:21:22 EDT

This archive was generated by hypermail 2.2.0 : Thu 08 Mar 2012 - 11:38:29 EST