[wiki] Core Function Reference

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.

ruud · 2009-10-20 16:53:47

jm wrote:

Clean up any spacing issues, such as no-space between commas (on some hurried-looking functions such as getCount())

How about avoiding double quotes (or at the very least not using double quotes unless needed), breaking long function calls on a new parameter instead of in a middle of a parameter and adding whitespace around concatenating dots:

	return getThing('select count(*) from ' . safe_pfx_j($table) . 'where ' . $where,
	                $debug);

or:

	return getThing('select count(*) from ' . safe_pfx_j($table) . 
	                'where ' . $where,
	                $debug);

and break the line at 78-80 chars if possible.

Not that I like seeing 1000 char lines, but breaking a line just because it exceeds a limit isn’t necessarily a good thing in all situations.

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).

+1. when coding for TXP I’ve tried to use tabs only for code indentation, to avoid crappy code layout for those that use a different tab width, but there are still lots of places where tabs are used for alignment.

/**
 * 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='')

Is it possible to add a blank line between the documentation and the function declaration?

Perhaps more important than the suggested PHPdoc documentation is comments on how the code works, especially in places where you otherwise have to stare at code for a day to understand why it was done in a specific way instead of a seemingly simpler way (which turns out not to work).

Bloke · 2009-10-20 18:55:03

ruud wrote:

How about avoiding double quotes (or at the very least not using double quotes unless needed), breaking long function calls on a new parameter instead of in a middle of a parameter and adding whitespace around concatenating dots:

Gets my vote. Breaking functions at logical parameter points makes more sense to me too than a hard-coded — arguably arbitrary nowadays — limit.

Perhaps more important than the suggested PHPdoc documentation is comments on how the code works, especially in places where you otherwise have to stare at code for a day to understand why it was done in a specific way instead of a seemingly simpler way (which turns out not to work).

Hehehe, yep. Definitely. I would guess this is where the multiline comment comes in handy so the short description becomes the overview and the optional long description gives programmer notes, if applicable (and if a reason for the particular implementation is known!) :

/**
 * Returns the number of rows matching a condition.
 * 
 * Could have been done by using sub-flange algorithmic flotsam, but that would break other functions.
 * @see rabbit_hole
 *
 * @param string  $table  Table name
 * @param string  $where  WHERE clause
 * @param bool    $debug  Print the query
 */
function getCount($table, $where, $debug='')

The @access and internal directives to help make two types of documentation — user and programmer — are overkill here imo. I doubt anybody would learn to use TXP by browsing the function reference, even if it did contain ‘end user’ notes :-)

ruud · 2009-10-20 19:52:00

Bloke wrote:

Hehehe, yep. Definitely. I would guess this is where the multiline comment comes in handy so the short description becomes the overview and the optional long description gives programmer notes, if applicable (and if a reason for the particular implementation is known!) :

No, that’s not what I mean. I was referring to adding inline comments (not PHPdoc comments) to make it easier to understand tricky parts of code for current and future maintainers.
The actual implementation details are not that interesting to end users. A black box with a good description and API is fine for most people. That’s where PHPdoc appears to more useful.

jm · 2009-10-20 19:59:58

ruud wrote:

How about avoiding double quotes (or at the very least not using double quotes unless needed), breaking long function calls on a new parameter instead of in a middle of a parameter and adding whitespace around concatenating dots:

That sounds and looks good.

Is it possible to add a blank line between the documentation and the function declaration?

I don’t think so, but I haven’t tested yet – no working phpdoc or doxygen install on this machine (and it’s been awhile since I’ve run either one).

Perhaps more important than the suggested PHPdoc documentation is comments on how the code works, especially in places where you otherwise have to stare at code for a day to understand why it was done in a specific way instead of a seemingly simpler way (which turns out not to work).

I agree – some inline comments (not phpdoc, just block or single-line) comments would be great.

Bloke wrote:

The @access and internal directives to help make two types of documentation — user and programmer — are overkill here imo. I doubt anybody would learn to use TXP by browsing the function reference, even if it did contain ‘end user’ notes :-)

I think access should be deprecated with PHP 5 anyways now that there are real modifiers. (PHP 4: “See, this variable is prefixed with an underscore, so it’s private. Yeah, you can’t touch that! But please don’t try it.”)…but yeah, we don’t need either access or internal.

Edit: Forgot to respond to Stef.

Last edited by jm (2009-10-20 20:06:00)

Textpattern CMS

Textpattern CMS support forum

#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

#25 2009-10-20 16:53:47

Re: [wiki] Core Function Reference

#26 2009-10-20 18:55:03

Re: [wiki] Core Function Reference

#27 2009-10-20 19:52:00

Re: [wiki] Core Function Reference

#28 2009-10-20 19:59:58

Re: [wiki] Core Function Reference

Board footer