[wiki] Core Function Reference

JanDW · 2009-10-04 23:41:15

That’s the idea; I was waiting to see how this would be received. No point starting unless there is some agreement as to whether to proceed, how to format each page, and willingness to write up the functions (which does take a bit of time).

I, for one, think it would be very useful. PHPXref is great, but I definitely need more than that.

Edit: In particular, Stef’s mention of PHPDoc brings up an entirely different direction in which such efforts might be usefully made.

Has PHPdocumentation been inserted/generated for txp? What direction do you mean?

So, IF this is a viable project, it will be up to us lesser lights to do the grunt work.

Eh… True enough I guess. But there’s still 25W and 160W bulbs amongst the lesser lights. My PHP bulb isn’t a halogen one , let me put it that way. But I’ll try help out when and where I can. Feel free to contact me and I’ll keep an eye out.

Last edited by JanDW (2009-10-04 23:41:52)

jsoo · 2009-10-05 00:29:29

JanDW wrote:

Has PHPdocumentation been inserted/generated for txp? What direction do you mean?

No (as far as I know), so that is the direction I mean. If the devs thought it a good idea to document the code a la PHPDoc or some other documentation generator (more structured than PHPxref, I mean) then it would be silly to manually document functions on TextBook.

I don’t really know anything about PHPDoc et al and I wonder about the utility of automatic documentation for Txp given its current … structure. And I expect that if the devs thought this a good idea it would have happened long ago. Stef hasn’t said anything discouraging so I expect the devs do not have such plans, hence it might be worthwhile to proceed.

JanDW · 2009-10-05 01:23:41

Alrighty. Tomorrow I’m having a stab at safe_rows…

jsoo · 2009-10-07 15:03:33

The discussion page now includes a prospective scheme of sub-categories and functions. Browsing this would be one way to find functions in need of documentation.

Bloke · 2009-10-19 16:22:14

Kinda lost sight of this thread, sorry. The functions you propose on the discussion page all seem fine to me. Certainly covers all the functions I’ve ever used ;-) If I get a chance I’ll populate a few pages using your template (thanks).

BTW, is this the right sort of place to post this kind of thing as a general lead-in:

== TXP functions ==

All internal TXP tag functions - and any plugins/functions you create - are in Textpattern's global scope. This is the reason why you '''always''' use your [[Reserved Plugin prefixes|reserved plugin prefix]] so it does't clash with anything else in Textpattern.

This does, however have a useful benefit: you can call any tag from within your code. So if you wanted to use the <code><txp:posted /></code> tag inside your plugin you would use it like this:

<pre>
$tag_content = posted(array());
</pre>

<code>$tag_content</code> would then hold the output of TXP's [[posted]] tag. Note that all functions take at least one parameter: an array of <code>'attribute' => 'value'</code> pairs. In this case we're accepting the defaults by not supplying any attributes '''''but we still send it an empty <code>array()</code>'''''.

If you wanted to add some parameters:

<pre>
$tag_content = posted(array('format' => '%H:%i', 'gmt' => '1'));
</pre>

Or should it go somewhere else? Any good ideas where it would fit?

jsoo · 2009-10-19 17:50:24

Bloke wrote:

Or should it go somewhere else? Any good ideas where it would fit?

I think it would be best linked directly from the Extending page. It could also linked from the Core Function Reference mininav.

Which brings up the larger subject of doing some housekeeping on the Extending page and its sub-pages. Things are a bit disorganized there.

Perhaps I should also go ahead and add a link to the function reference. Was waiting to see if there would be enough interest for this to take off.

JanDW · 2009-10-19 18:15:41

jsoo wrote

Perhaps I should also go ahead and add a link to the function reference. Was waiting to see if there would be enough interest for this to take off.

I think that would be good, it might get forgotten otherwise, it could be really valuable

Bloke wrote:

Or should it go somewhere else? Any good ideas where it would fit?

Maybe it would fit in with your plugin basics article?

Sorry I haven’t started yet myself, lack of time and needing to look into it more is a bad combo…

Last edited by JanDW (2009-10-19 18:17:56)

jsoo · 2009-10-19 20:02:50

OK, link added (under “Tools and Aides” [which would perhaps be better as “Tools and Aids”]). And filled out another function page (safe_row).

jm · 2009-10-19 20:37:13

I think submitting phpdoc patches is a great idea. We could set up a separate phpdoc/doxygen browser in the future, but it would certainly be nice having actual comments in the source code.

So for each patch…

For the function you’re documenting, remove the useless // ------------... line and replace it with phpdoc comments
Remove the leftmost-tab indent on most, if not all functions (no idea why it’s indented)
Clean up any spacing issues, such as no-space between commas (on some hurried-looking functions such as getCount()) and break the line at 78-80 chars if possible.
The TXP source code uses tabs, so stick with it, but don’t use tab characters to align things (IIRC, publish.php fails at this). (It’d be great of the codebase standardized on spaces like PEAR and other projects, but that probably won’t happen.)
svn diff > ~/Desktop/documented_functionname.diff
Email the dev list with your patch

For example, the current getCount():

//-------------------------------------------------------------
        function getCount($table,$where,$debug='')
        {
                return getThing("select count(*) from ".safe_pfx_j($table)." where $where",$debug);
        }

Modified getCount()

/**
 * Returns the number of rows matching a condition.
 *
 * @param string  $table  Table name
 * @param string  $where  WHERE clause
 * @param bool    $debug  Print the query
 */
function getCount($table, $where, $debug='')
{
	return getThing("select count(*) from ".safe_pfx_j($table)."
	                 where $where", $debug);
}

Note that there’s a tab character at the beginning of the where line, but the rest of the alignment is performed with spaces.

In your editor, you should be able to switch between tabs and spaces (expanded tabs). Hopefully, your editor can also highlight tab characters. In Vim, you can write a simple function to set expandtab for spaces or set noexpandtab for real tabs (I have this mapped to \-<Tab>). To highlight tab characters, use set list listchars=tab:<digraphofyourchoice>,trail:<digraph> where you can enter the a digraph :h ctrl-k). I have mine mapped to a double angular quote (<C-k> >>) as you can see below:

Last edited by jm (2009-10-19 20:38:07)

jsoo · 2009-10-19 22:00:01

jm wrote:

I think submitting phpdoc patches is a great idea. We could set up a separate phpdoc/doxygen browser in the future, but it would certainly be nice having actual comments in the source code.

What say, Dev team? Is this a good fit?

redbot · 2009-10-19 22:57:23

Just wanted to thank you all for the excellent work you are doing with the Core Function Reference and Textbok.
This adds great value to txp documentation.

Bloke · 2009-10-20 08:46:58

jm wrote:

I think submitting phpdoc patches is a great idea. We could set up a separate phpdoc/doxygen browser in the future, but it would certainly be nice having actual comments in the source code.

fwiw, I’m up for it. Dunno about the others; though I notice in the recent stuff Robert added he snuck some phpdoc syntax in there (see bottom of txplib_misc.php for example).

At the expense of larger files it does mean we get documentation “for free” without having to keep a separate effort like Textbook up to date with core alterations. I’m all for reducing the overhead of documentation, even if it means extra work in the transition period.

Remove the leftmost-tab indent on most, if not all functions (no idea why it’s indented)

Yup, I never knew why it was indented either. Bugs me a little bit to have that wasted space that could be put to better use. Removing the start tab alone on txplib_misc.php saves 2Kb! Also removing the // ------... junk reclaims 10Kb in total… makes space for some comments at least without increasing the file size too much ;-)

The TXP source code uses tabs, so stick with it, but don’t use tab characters to align things

Fine by me. My text editor du jour (ConText) has “smart indent” on, which does the auto-indent stuff up to the same level as the previous line. What I didn’t realise until I just tried it with your example, was that if you add leading spaces as well to further align stuff it copies those to the next line as well. Neat. So that’s me sold on the idea.

Textpattern CMS

Textpattern CMS support forum

#13 2009-10-04 23:41:15

Re: [wiki] Core Function Reference

#14 2009-10-05 00:29:29

Re: [wiki] Core Function Reference

#15 2009-10-05 01:23:41

Re: [wiki] Core Function Reference

#16 2009-10-07 15:03:33

Re: [wiki] Core Function Reference

#17 2009-10-19 16:22:14

Re: [wiki] Core Function Reference

#18 2009-10-19 17:50:24

Re: [wiki] Core Function Reference

#19 2009-10-19 18:15:41

Re: [wiki] Core Function Reference

#20 2009-10-19 20:02:50

Re: [wiki] Core Function Reference

#21 2009-10-19 20:37:13

Re: [wiki] Core Function Reference

#22 2009-10-19 22:00:01

Re: [wiki] Core Function Reference

#23 2009-10-19 22:57:23

Re: [wiki] Core Function Reference

#24 2009-10-20 08:46:58

Re: [wiki] Core Function Reference

Board footer