I often find myself with fairly complex data that represents something that my objects will be working on. For example, in a task-list app, several objects might work with an array of tasks, each of which has attributes, temporal expressions, sub tasks and sub sub tasks, etc.
One object will collect data from web forms, standardize it into a format consumable by the class that will save them to the database, another object will pull them from the database, put them in the standard format and pass them to the display object, or the update object, etc.
The data itself can become a fairly complex series of arrays and sub arrays, representing a ‘task’ or list of tasks.
For example, the below might be one entry in a task list, in the format that is consumable by the various objects that will work on it. Normally, I just document this in a file somewhere with an example. However, I am thinking about the best way to add it to something like PHPDoc, or another standard doc system.
Where would you document your consumable data formats that are for many or all of the objects / methods in your app?
Array
(
[Meta] => Array
(
//etc.
)
[Sched] => Array
(
[SchedID] => 32
[OwnerID] => 2
[StatusID] => 1
[DateFirstTask] => 2011-02-28
[DateLastTask] =>
[MarginMonths] => 3
)
[TemporalExpressions] => Array
(
[0] => Array
(
[type] => dw
[TemporalExpID] => 3
[ord] => 2
[day] => 6
[month] => 4
)
[1] => Array
(
[type] => dm
[TemporalExpID] => 32
[day] => 28
[month] => 2
)
)
[Task] => Array
(
[SchedTaskID] => 32
[SchedID] => 32
[OwnerID] => 2
[UserID] => 5
[ClientID] => 9
[Title] => Close Prior Year
[Body] =>
[DueTime] =>
)
[SubTasks] => Array
(
[101] => Array
(
[SchedSubTaskID] => 101
[ParentST] =>
[RootT] => 32
[UserID] => 2
[Title] => Review Profit and Loss by Class
[Body] =>
[DueDiff] => 0
)
[102] => Array
(
[SchedSubTaskID] => 102
[ParentST] =>
[RootT] => 32
[UserID] => 2
[Title] => Review Balance Sheet
[Body] =>
[DueDiff] => 0
)
[103] => Array
(
[SchedSubTaskID] => 103
[ParentST] =>
[RootT] => 32
[UserID] => 2
[Title] => Review Current Year for Prior Year Expenses to Accrue
[Body] => Look at Journal Entries that are templates as well.
[DueDiff] => 0
)
[104] => Array
(
[SchedSubTaskID] => 104
[ParentST] =>
[RootT] => 32
[UserID] => 2
[Title] => Review Prior Year Membership from 11/1 - 12/31 to Accrue to Current Year
[Body] =>
[DueDiff] => 0
)
[105] => Array
(
[SchedSubTaskID] => 105
[ParentST] =>
[RootT] => 32
[UserID] => 2
[Title] => Enter Vacation Accrual
[Body] =>
[DueDiff] => 0
)
[106] => Array
(
[SchedSubTaskID] => 106
[ParentST] => 105
[RootT] => 32
[UserID] => 2
[Title] => Email Peter requesting Vacation Status of Employees at Year End
[Body] => We need Employee Name, Rate and Days of Vacation left to use.
We also need to know if the employee used any of the prior year's vacation.
[DueDiff] => 43
)
[107] => Array
(
[SchedSubTaskID] => 107
[ParentST] =>
[RootT] => 32
[UserID] => 2
[Title] => Grants Receivable at Year End
[Body] =>
[DueDiff] => 0
)
[108] => Array
(
[SchedSubTaskID] => 108
[ParentST] => 107
[RootT] => 32
[UserID] => 2
[Title] => Email Peter Requesting if there were and Grants Receivable at year end
[Body] =>
[DueDiff] => 43
)
)
)
I would document with and in the code that defines the data. One way to self document is to use classes with well named attributes instead of arrays or hashes when things start to become complex. Just use comments sparingly to clear up any unobvious areas. Assume that the is smarter than you and avoid comments that clutter things.