Documentation Conventions for Beehive
Still to be discussed/ratified
Formatting
- Indents are four spaces.
- rich / eddie / steveh +1
- Multiline XML text content is indented, on its own line:
...and not:
<p> some content another line </p>
<p>some content another line</p>
- rich / eddie / steveh +1
An exception is the <source> tag.
The following looks ugly in the browser because it produces excessive vertical white space:Instead, use the following:<source><![CDATA[ <netui:span value="${pageScope.fooAttribute}"/> ]]></source>
<source><![CDATA[ <netui:span value="${pageScope.fooAttribute}"/> ]]></source>
- steveh / rich +1
- eddie -0 – this makes the code snippet harder to edit and the whitespace isn't excessive
- rich / eddie / steveh +1
- Right margin is 120 characters.
- daryl / rich / eddie / steveh +1
- Identifiers for <section> tags are camelCase rather than dashed. So, use "camelCase" rather than "camel-case" or "camel_case".
- eddie / rich +1
- eddie / rich +1
Terminology
- "NetUI", not "Netui".
- rich / steveh +1
- "Page Flow" for the controller-related piece of NetUI. 'Note that "NetUI" is a top-level component alongside Controls and WSM. Page Flow is a part of NetUI – it is never used as a top-level Beehive component.
- rich / steveh +1
- "page flow" for a single directory path that contains a controller and a set of pages. Common noun.
- rich / steveh +1
- "NetUI web project" to describe a set of files that can be built into a webapp. In most cases we will be talking about a "NetUI web project", unless we're talking about the actual thing that got built/deployed.
- rich / steveh +1
- "page flow controller" for the controller class (extended from Page{{`Flow}}`Controller) piece of a page flow.
- rich / steveh +1
- "shared flow controller" for a controller class that extends Shared{{`Flow}}`Controller and which can be used by page flows.
- rich / steveh +1
- "Shared Flow" for the feature that allows you to create/use shared flow controllers.
- rich / steveh +1
- "a shared flow" – delete this term from the doc – replace with "a shared flow controller".
- rich +1 steveh +1
- "controller class" as a general term for a page flow controller or a shared flow controller (e.g., the class myPageFlow.MyController)
- rich / steveh +1
- "controller file" – delete this term from the doc
- rich /steveh +1
- "JSP", not "JSP page"
- rich / steveh +1
- "<netui:textBox>" not "textBox"
- steveh +1 (This is probably worth debating.)
- rich: +1, even though the user could always choose something other than
netui
for the prefix. How about making this hyperlinked to the TextBox tag doc as well?
- "form bean" not "Form{{`Data" or "Action}}`Form"
- steveh / rich +1
Mechanics
- We always use full xpath in "site:..." links.
- daryl / eddie /steveh +1
- rich +0
Code Formatting
- TODO - need rules about code formatting in samples for XML, JSP, and Java