Rewrite section comments in a uniform format

[dreadnaut]

Originally reported on Google Code with ID 244

The code map I wrote last March (2013-03-25) is already out of date. I use it quite
often to find my way around the code, but keeping it up do date manually requires too
much work.

If I were to mark important sections of the files with comments with a consistent format,
we could regenerate the map with a simple grep.

Something along these lines:

//- table actions
...
  //- create a new table (table_create)
  ...
  //- delete all rows and vacuum a table (table_empty)

Calling 'grep -n "//-" index.php' would give us a nice, indented map of the code, maybe
reducing the need for those '////////////////////////[...]'

Reported by dreadnaut on 2014-01-11 19:41:05

[Christopher Kramer]

Yes, feel free to add comments like this to the source code.
It surely would be useful.

Maybe an even more structured format would help to make the code better searchable.
In phpLiteAdmin code, I usually search for the piece of code where actions are performed.
e.g. where the "column_edit" form code is and where the "column_edit&confirm=1" action
perform part is. Currently I use the editor search function a lot to find these places.
But action names like "column_edit" occur at several places where the action is not
really performed and the form is not generated. So I have to search for the next occurrence
several times to get where I am heading for.
So maybe comments like this would be very useful because you could find the place you
are looking for very fast:
// - form to edit a column (ACTION column_edit UNCONFIRMED)
and where the action is really performed:
// - edit a column (ACTION column_edit CONFIRMED)

So you can search for "column_edit UNC" or "column_edit CONF" and you are directly
where you want to go.

Although better comments are good and stuff like this will help for the time being,
we should in the long-run really use more OOP. This would make finding the right place
a lot simpler, so you can just look for the edit() method of the Column Class for example.

Reported by crazy4chrissi on 2014-01-15 09:24:28

[dreadnaut]

> Although better comments are good and stuff like this will help
> for the time being, we should in the long-run really use more OOP.

That's why I wouldn't spend to much time on this. I would just make sure that all the
important sections have a comment 'heading' and we know (more or less) where stuff
is.

Patch soon ;)

Reported by dreadnaut on 2014-01-16 12:26:50 - Status changed: Accepted

[dreadnaut]

Here's is the diff for the new comments. The syntax I used:

1) map comments start with '//- '
2) larger html chunks are marked with 'HTML: '
3) switch values are written as '=string'

The last point should make actions easier to find in-editor; let me know if it works
for you.

Also attached is the source map that comes from running

 grep -n //- index.php

Reported by dreadnaut on 2014-01-17 12:44:34 - Status changed: Started

<hr> * Attachment: comment-map.patch * Attachment: map.txt

[Christopher Kramer]

ok, cool. Only thing I noticed is a typo:
//- Delete and existing database
should be
//- Delete an existing database

Feel free to commit.

Reported by crazy4chrissi on 2014-01-17 13:17:27

[dreadnaut]

This issue was closed by revision r458.

Reported by dreadnaut on 2014-01-17 13:20:31 - Status changed: Fixed