Folding to produce a high-level index of code

[Noah Spurrier]

I have folding set to use expr. I have a foldexpr that
identifies lines for functions and classes in PHP.
Lines that are part of a function are folded.
Function definition lines are NOT folded.
This gives me a single level of folding that works like
an index to my code. This works great.

Is it possible to have an open fold include a few lines BEFORE the
beginning of the fold? For example, it's common in PHP to have a
phpdoc comment before the function definition.
When all folds are closed I see just a list of function names.
When I open a fold I see the entire body of the function, but
I don't see the comment before the function.

I'm sure I could get the fold expression to work so that it starts the
fold on the comment BEFORE the function definition, but then when I closed
the fold I would not see the function name.

Perhaps I could set the fold to start at the comment before the
function definition and set the 'foldtext' to be the
text of the line with the function definition. I shall mull that over.
In the mean time, if anyone has any suggestions or has already done
this then please let me know.

So when I have all folds closed I see my code like this:

    function reverse_zipcode ($zipcode)
    +-- 10 lines: {----------------------------------------------------
    function get_inventory ()
    +-- 28 lines: {----------------------------------------------------
    function delete_inventory ()
    +--  5 lines: {----------------------------------------------------
    function touch_sql ($sql)
    +-- 21 lines: {----------------------------------------------------
    function see_sql ($sql,$fetch_mode=DB_FETCHMODE_OBJECT)
    +-- 20 lines: {-----------------------------------------------------

If I wanted to view "delete_inventory" I would click on the + to open
the fold to see something like this (note how the comment BEFORE
the function is also show):

    function reverse_zipcode ($zipcode)
    +-- 10 lines: {----------------------------------------------------
    function get_inventory ()
    +-- 28 lines: {----------------------------------------------------
    /**
     * This deletes unqualified inventory from t_inventory.
     * The table "inv_delete" is used to find unqualified inventory
     * scheduled for deletion.
     * @see function create_inv_delete
     */
    function delete_inventory ()
    {
        $sql = "DELETE inventory FROM inventory, inv_delete WHERE
    inventory.inventory_id=inv_delete.inventory_id;";
        touch_sql ($sql);
    }
    function touch_sql ($sql)
    +-- 21 lines: {----------------------------------------------------
    function see_sql ($sql,$fetch_mode=DB_FETCHMODE_OBJECT)
    +-- 20 lines: {-----------------------------------------------------

Currently, the best I can do is to show everything below the fold.
This is nice, but the documentation comment remains hidden, like this:

    function reverse_zipcode ($zipcode)
    +-- 10 lines: {----------------------------------------------------
    function get_inventory ()
    +-- 28 lines: {----------------------------------------------------
    function delete_inventory ()
    {
        $sql = "DELETE inventory FROM inventory, inv_delete WHERE
    inventory.inventory_id=inv_delete.inventory_id;";
        touch_sql ($sql);
    }
    function touch_sql ($sql)
    +-- 21 lines: {----------------------------------------------------
    function see_sql ($sql,$fetch_mode=DB_FETCHMODE_OBJECT)
    +-- 20 lines: {-----------------------------------------------------

Yours,
Noah