Closed Bug 141036 Opened 22 years ago Closed 22 years ago

Add INTERFACE comments to some templates


(Bugzilla :: User Interface, defect)

Not set



Bugzilla 2.16


(Reporter: gerv, Assigned: gerv)



(1 file, 1 obsolete file)

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.

Keywords: patch, review
Target Milestone: --- → Bugzilla 2.16
Attached patch Patch v.1 (obsolete) — Splinter Review
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 :-)

Some suggestions for improvements follow. 

+++ template/en/default/admin/attachstatus/list.html.tmpl
+  # 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/help.html.tmpl and
which don't look like interface comments. Stray code from other patches?
Attached patch Patch v.2Splinter Review
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.)

Attachment #81573 - Attachment is obsolete: true
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...
Attachment #81764 - Flags: review+
Patch 1 checked in. patch 2 to follow when I get time...

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, 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.
Yes. Sorry for the confusion. Marking fixed.

Bug 142948 has been opened to continue this work.

Closed: 22 years ago
Resolution: --- → FIXED
Summary: Add INTERFACE comments to all templates → Add INTERFACE comments to some templates
QA Contact: matty_is_a_geek → default-qa
You need to log in before you can comment on or make changes to this bug.