141036 - Add INTERFACE comments to some templates

Status: RESOLVED FIXED

(Bugzilla :: User Interface, defect)

Description

[Gervase Markham [:gerv]]

INTERFACE comments are good; they allow admins to see what's changed about an
interface to a template. We should have them everywhere. 

As they are just comments, adding them is just a case of writing them.

Gerv

Comment 1

[Gervase Markham [:gerv]]

Attachment: Patch v.1

Here's as many as I could do before I got bored. :-) I might do more later.
It's a big job, and any help is appreciated - particularly from the original
authors of templates :-)

Gerv

Comment 2

[Jouni Heikniemi]

Some suggestions for improvements follow. 

--
+++ template/en/default/admin/attachstatus/list.html.tmpl
...
+[%# INTERFACE:
+  # statusdefs: list of hashes. may be empty. Each hash has six members:
+  #   name: string. The name of the attachment status.
+  #   description: string. Its description.
+  #   sortkey: integer. What order to sort them in.
+  #   product: string. The product to which it applies.
+  #   id: integer. Its internal ID number.
+  #   attachcount: integer. How many attachments have that status
+  #%]
--

The "sortkey" description shouldn't be plural if the others are singular. How
about using "sorting priority", "sorting order position" or a similar term in
the description of all the sortkey variables? The word "it" is used fairly
loosely here, I think repeating the words "attachment status" a bit more often
would be good for the sake of clarity.


--
+++ template/en/default/attachment/created.html.tmpl
...
+  # contenttypemethod: string. How we got the content type of the attachment.
--

What are the possible values for contenttypemethod?

--
+  # mailresults: string. who was mailed, and who wasn't.
--

How is this indicated in the string? Who was, who wasn't? A format example maybe?
(this comment applies to several other instances as well)

--
+++ template/en/default/bug/create/comment.txt.tmpl	
...
+  # used to pull out various custom fields and format an intial Description
--

intial -> initial, I suppose.

--
+++ template/en/default/global/header.html.tmpl
...
+  # extra: string. Other stuff to go in the header.
--

Ummh... What stuff? <link> elements? This is a bit too generic to be useful. An
example or a pointer to source or something, please?

--
+  # message: string. A message to display to the user.
--

Should (for example) this mention "may contain HTML", since some other interface
comments do that too?

--
+++ template/en/default/reports/components.html.tmpl	
...
+  #   name: string. Name of the tab (used internally.)
+  #   description: string. Description of the tab (used in tab title.)
--

"What the *** 'tabs' are you talking about? Isn't this supposed to be the
components list?" ;--)



The patch also contains a bunch of stuff from
template/en/default/global/footer-menu.html.tmpl,
template/en/default/global/help.html.tmpl and
template/en/default/search/search-help.html.tmpl,
which don't look like interface comments. Stray code from other patches?

Comment 3

[Gervase Markham [:gerv]]

Attachment: Patch v.2

Thank you for your useful comments :-) I'm highly surprised anyone had the
energy to review these. I expected them to be "reviewed with use" :-)

This attachment has all the requested changes (except for mailresults - that's
going away anyway when bbaetz spanks processmail.)

Gerv

Comment 4

[Bradley Baetz (:bbaetz)]

Comment on attachment 81764 [details] [diff] [review]
Patch v.2

r=bbaetz x2. Not sure if I like the 'no interface' comment, but I can't think
of anything better, so...

Comment 5

[Gervase Markham [:gerv]]

Patch 1 checked in. patch 2 to follow when I get time...

Gerv

Comment 6

[Gervase Markham [:gerv]]

This is a massive job, and I'm probably not going to finish it by 2.16. It's not
a blocker for the release; it should not obstruct RC1.

Gerv

Comment 7

[Dave Miller [:justdave]]

Gerv, by "patch 1" are you refering to "Patch v2" on this bug, which has the
first and second review on it already?

If so, please mark this bug fixed and open a new bug to finish the job.  I
really dislike having open bugs with patches that have already been checked in
on them.

Comment 8

[Gervase Markham [:gerv]]

Yes. Sorry for the confusion. Marking fixed.

Bug 142948 has been opened to continue this work.

Gerv