Andy, can you take a shot at updating the sp_get_auth() codex entry to see it in practice?

#2 are you suggesting going back through the code and changing variable names?

#3 formatted code examples?  do you mean syntax highlighter?  forgot about it will change to that and see if its what you meant…

#5 I dont think we should list the permissions there.  perhaps a new section under simple press api? I think that would be appropriate…

updated the sp_get_auth() example to use the code display…  think I like it better!

Brandon, fyi, to do that, in the visual editor, you will see an icon that looks like a highlighter… select it, pick the language and then paste in the code you want to highlight…

Looks like a highlighter?

Here is what I see using the visual editor and turning on ‘kitchen sink’

Is that the same as you see? Which one is the highlighter?

hmmm… maybe not available to your role… have increased role to editor… please check again…

#2 – Eh? I am talking about this codex entry and the use of the variable names in the text.

For example you have used $id in the definition at the top and $forumid in the examples. This should be consistently $forumid. Same with the use of $user_id and $userid. And I was suggesting that $check would be better if it described the item in question… in this case $permission.

#4 – Any comments on this one?

#2 I think it would be a mistake to change only the codex entry in that manner.  Then it would not agree with the code itself…  which is why I asked if you were suggesting to change the code…  the variables used, $check, $id, $userid are exactly what is used in the code…  I think the codex entry variables should match the code variables…

#4 fine with it… silence was concurrence…

Mr Papa said

#2 I think it would be a mistake to change only the codex entry in that manner.  Then it would not agree with the code itself…  which is why I asked if you were suggesting to change the code…  the variables used, $check, $id, $userid are exactly what is used in the code…  I think the codex entry variables should match the code variables…

I very strongly disagree with this. This is documentation. If the codex is clear, precise and consistent there is no need for anyone to ever look at the code itself. We are talking about function parameters and the way to make them clear, usable, unequivocal and unambiguous is to describe them properly with meaningful names.

Using shortened variable names in code is one thing (although I do try and use the full terms like ‘forumid’, ‘topicid’, ‘userid’ in my code as much as possible). Using ambiguous variable names in documentation is just confusing. To then go on to cite examples that do not even use the same variable names as those in the definition at the top is likely to totally confuse the less able and skilled.

If you prefer to go through the code and change variable names in there then I say yes – we need to do it. But personally I see no need whatsoever to do so.

wow. surprised.

wouldnt have thought you would be for the documentation not matching the code…

btw, all the names on that example codex entry were already changed a day or two ago to be consistent with each other – so not really part of the discussion since already agreed and to and changed…

the only question left is whether the docs match the code in variable names…  If everyone else is good with them not, I can certainly get over it…

Mr Papa said

hmmm… maybe not available to your role… have increased role to editor… please check again…

I do see it now, thanks.

good to hear.