On Mon, Mar 22, 2010 at 10:22 AM, Markus Weimar <[email protected]> wrote: > > First, I would list the parameters for each function above its code. > In my opinion a good function doc string tells you what the function > does, what the parameters are, and what the function returns. At a > minimum.
I'd like to see the more expanded docs put on BoltWire.com not in the code. I tried to add a single line of "brief" notes to each function only grudgingly, though it did make a cool help system possible. I'm not enthusiastic about changing the internal code docs--other than specific text replacements were suggested of course. Things I probably won't change: * More than a single line of docs per function * Dropping the all caps. In my view the latter makes it easier to distinguish between code and docs, and are easier for me to ignore! Not to mention the time involved in redoing every single one... > Take breadcrumb as an example: > > ## TAKES A PAGE NAME AND BREAKS IT DOWN TO A DISPLAY OF CLICKABLE > LINKS UP IT'S HIERARCHY. PAGE NAME USED DEFAULTS TO CURRENT PAGE, BUT > CAN BE RESET BY PARAMETER PAGE OR #1. OTHER OPTIONAL PARAMETERS > INCLUDE SEPARATOR (DEFAULT >) AND NAME=LINK/NONE (DEFAULT TEXT) TO > DEFINE HOW LAST PAGE PART IS DISPLAYED. SET TEXT=TRUE TO DEACTIVATE > LINKS. USE OFFSET=1 TO IGNORE THE FIRST PAGE PART. USE RTL=TRUE FRO > RIGHT-TO-LEFT DISPLAY > > You need to read that whole paragraph and it's impossible to read > caps-lock. What about a custom doc string that can be used by > action=help? Think about it: function docs right in your installation > without going to BoltWire.com, reading caps-lock or reading source > files. This seems adequate to me for it's purpose. The help system is just brief hints for advanced users. I'm assuming people will have to test it out a bit to fully grasp it all. I'd like to see much more thorough online docs--not try to move those potential online docs into the code. > For these pages your proposed hierarchy is great: > docs > docs.handbook > docs.handbook.functions > docs.handbook.functions.breadcrumb I'll see if I can find some time to move over all the pages, but not sure when I can do it. To be honest, I'd be tempted to just start over and delete the entire docs.barn hierarchy. To be honest, I thought I had already... Cheers, Dan -- You received this message because you are subscribed to the Google Groups "BoltWire" group. To post to this group, send email to [email protected]. To unsubscribe from this group, send email to [email protected]. For more options, visit this group at http://groups.google.com/group/boltwire?hl=en.
