|
DocumentationGuidelines
We know what volunteering is like, so we want to make it as efficient for everyone as possible. Here are the rules of the road for contributing documentation to the project.
The Docs are as important as the code itself. How is anyone going to use Wheels if they can't learn how to? And the great docs by Allaire/Macromedia/Adobe are a big reason why you've always loved ColdFusion, right? Steve, Our PersonaIn hopes of keeping everyone in the same spirit, let's give the narrator of the website and documentation the name Steve. Let's pretend that we're Steve when writing in order to keep things interesting, friendly to our audience, and consistent. Here's a description of Steve's persona. Being a Wheels nerd, you'll probably find himself easy to relate to.
ProcessAll documentation should go through these processes. Let's not be a bunch of cowboys like MySpace developers!
Chapters in the Reference GuideThe reference guide contains narrative chapters about using the framework. It should contain a wealth of code samples and should be written in clear, concise language. Video TutorialsVideo tutorials should cover an area of Wheels that hasn't been covered in previous videos. Please publish the video in Flash or Quicktime format at a maximum width of 720 pixels. The core team will make the final decision on whether or not the video will be published on the Wheels website, but you may post the video on your blog, YouTube, or anywhere else that you please. API DocumentationThe API documentation should be very clear and concise. Let's keep Steve out of it for the most part. He understands. Example API Function DocumentationMost descriptions of Wheels' functions should follow this general format, inspired by the CFML function reference in the ColdFusion 8 Live Docs.
A concise description of what the function does. Also include any notes like what types of values that are supported and returned.
Short description of what is returned from the function, if anything.
functionName(argument1, argument2, [optionalArgument])
Example code for common use cases. Generating API Documentation in Core Source CodeWe will be generating all API documentation using attributes in the Wheels core code's <cffunction> and <cfargument> tags. This metadata will be parsed and imported into a database for use on the website. Use Textile and HTML formatting where appropriate. Function DocumentationWithin each public function (those not beginning with a $ character), use the following attributes:
Note that you should use the hint attribute to clear up any ambiguities caused by the function's declaration. For example, if a function returns either an object or a string, this may only be indicated in the source code as returntype="any". Clearly address this ambiguity in the hint attribute. Here is an example of what the source code would look like for the addRoute() function declaration. Notice that clear indentation and proper choice of single quotes for the examples attribute. <cffunction name="addRoute" returntype="void" access="public" output="false" hint="Adds a new route to your application."
examples=
'
<cfset addRoute(name="userProfile", pattern="user/[username]", controller="user", action="profile")>
'
categories="global" chapters="using-routes">Here is another example for the new() function: <cffunction name="new" returntype="any" access="public" output="false" hint="Creates a new object based on supplied properties and returns it. The object is not saved to the database, it only exists in memory. Property names and values can be passed in either using named arguments or as a struct to the `properties` argument."
examples=
'
<--- Blank model object --->
<cfset newAuthor = model("author").new()>
<!--- Built with data from the params.author struct --->
<cfset newAuthor = model("author").new(params.author)>
<!--- Built with default values for firstName and lastName --->
<cfset newAuthor = model("author").new(firstName="John", lastName="Doe")>
'
categories="model-class" chapters="creating-records" functions="create">List of CategoriesHere is a current list of categories and subcategories that can be used in the categories attribute of the cffunction tags.
Argument DocumentationUse all standard CFML attributes to document what is expected of function arguments. Much like the functions' documentation, the argument's hint attribute should be used to clear up any ambiguities associated with type="any" as an expected type. One extra rule applies to argument documentation though. In some places of the source code, there are hints that refer to other functions' versions of that argument. Take a look at the defaults argument of the save() function, for example: <cfargument name="defaults" type="boolean" required="false" default="#application.wheels.functions.new.defaults#" hint="See documentation for @save."> In this case, the documentation in the website database will be copied from the hint attribute of the save() function's defaults argument. Prefix the associated function with the @ character like in the example above. |
Sign in to add a comment
