Documentation Conventions for Beehive

Still to be discussed/ratified

Formatting

  1. Indents are four spaces.
    • rich / eddie / steveh +1
  2. Multiline XML text content is indented, on its own line: 
             <p>
             some content
             another line
         </p>
    ...and not: 
           <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: 
         <source><![CDATA[
       <netui:span value="${pageScope.fooAttribute}"/>
   ]]></source>
      Instead, use the following: 
         <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
  3. Right margin is 120 characters.
    • daryl / rich / eddie / steveh +1
  4. Identifiers for <section> tags are camelCase rather than dashed. So, use "camelCase" rather than "camel-case" or "camel_case".
    • eddie / rich +1

Terminology

  1. "NetUI", not "Netui".
    • rich / steveh +1
  2. "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
  3. "page flow" for a single directory path that contains a controller and a set of pages. Common noun.
    • rich / steveh +1
  4. "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
  5. "page flow controller" for the controller class (extended from Page{{`Flow}}`Controller) piece of a page flow.
    • rich / steveh +1
  6. "shared flow controller" for a controller class that extends Shared{{`Flow}}`Controller and which can be used by page flows.
    • rich / steveh +1
  7. "Shared Flow" for the feature that allows you to create/use shared flow controllers.
    • rich / steveh +1
  8. "a shared flow" – delete this term from the doc – replace with "a shared flow controller".
    • rich +1 steveh +1
  9. "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
  10. "controller file" – delete this term from the doc
    • rich /steveh +1
  11. "JSP", not "JSP page"
    • rich / steveh +1
  12. "<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?
  13. "form bean" not "Form{{`Data" or "Action}}`Form"
    • steveh / rich +1

Mechanics

  1. We always use full xpath in "site:..." links.
    • daryl / eddie /steveh +1
    • rich +0

Code Formatting

  1. TODO - need rules about code formatting in samples for XML, JSP, and Java
  • No labels