mnemonics in xh-phpdoc

Discussions and requests related to new CMSimple features, plugins, templates etc. and how to develop.
Please don't ask for support at this forums!
Post Reply
svasti
Posts: 1651
Joined: Wed Dec 17, 2008 5:08 pm

mnemonics in xh-phpdoc

Post by svasti » Mon Dec 29, 2014 11:15 am

The variable names form Peter Harteg time are very short and thus difficult to memorize...
E.g.

Code: Select all

/**
 * The number of pages.
 *
 * Treat as <i>read-only</i>.
 *
 * @global int $cl
 *
 * @access public
 */
$cl = 0;
Wouldn't it be possible to add something like

Code: Select all

/**
 * The number of pages (short for: *C*ount till *L*ast page).
 ...
or

Code: Select all

/**
 * The number of pages.
 *
 * Short for: *C*ount till *L*ast page.
 *
...
Some variable names may need a creative approach, e.g. $hc, which has changed its meaning in time. What about a new meaning as "*H*eadline *C*ollection"?

I am still trying to understand what variables there are in XH, what they do and what they mean.

cmb
Posts: 14225
Joined: Tue Jun 21, 2011 11:04 am
Location: Bingen, RLP, DE
Contact:

Re: mnemonics in xh-phpdoc

Post by cmb » Mon Dec 29, 2014 12:59 pm

svasti wrote:The variable names form Peter Harteg time are very short and thus difficult to memorize...
Yes, I fully agree, but some do prefer these short names.
svasti wrote:Wouldn't it be possible to add something like
[ code suggestions ]
I'd say: go ahead! :) Improving the API documentation can IMO be done without any voting.

Minor notes: "count till last page" might be misleading, because when $cl == 10, the last page's index is 9. Maybe it's better to say "count of pages". Doing the emphasis of the abbreviated letters is a good idea, and it's fine with me to use asterisks for it, because that's the phpDocumentor 2 way, but you could also use HTML markup (e.g. <b>) what is understood by PhpDocumentor 1.
svasti wrote:Some variable names may need a creative approach, e.g. $hc, which has changed its meaning in time. What about a new meaning as "*H*eadline *C*ollection"?
That seems to be easily misleading, because $hc is not a collection of headlines, but rather a collection of page indexes. We talked about the name $hc in another thread a while ago, but I'm not able to find it. Do you know where it was?
svasti wrote:I am still trying to understand what variables there are in XH, what they do and what they mean.
Unfortunately, that's not an easy task. There are way to many global variables, many of them having cryptic names, some of them having hard to document values (e.g. $hc, which is an array of ints, but what do the ints mean?), some of them being adversly defined ($c, $u, $h, $l would have better be defined as a single array of records or objects), and there are even these awkward ad-hoc variables. And after all they are variables so they could change any time.
Christoph M. Becker – Plugins for CMSimple_XH

Post Reply