boazsegev / plezi

I'm rewriting Plezi, but rewriting the documentation is far from being my forte... for one, I'm not a native English speaker.

If you want to write a tutorial or add documentation for the Ruby code, please jump in.

You'll need to fork this project for adding YARD documentation using code comments or fork the documentation web application if you're writing any tutorials or help articles.

Help articles and tutorials are written using markdown (the documentation application will convert it all to html, no worries).

Most of the documentation currently references the older (v.0.12.x) API and is dire need of a total rewrite... even simply deleting irrelevant parts will be a help.

Thanks!

I'd like to help out a bit with documentation, when I can.

I've cloned the documentation repo to focus on tutorials and help articles, for now, and made my first pull request to give it a try.

Let me know if you'd like me to explain any of the changes I've made.

Thank you again for the help!

Not only did you help refine the documentation, but also exposed some code that needed clarification.

By the way most projects (this one as well) include YARD style documentation in the code itself. This is included in comments placed above documented methods / classes.

This documentation is published automatically at https://www.rubydoc.info.

For example:

plezi/lib/plezi/api.rb

Lines 8 to 9 in 8f6b1a4

    
           # Get / set the template folder for the {Controller#render} function. 
        
           attr_accessor :templates

Or:

plezi/lib/plezi/api.rb

Lines 40 to 53 in 8f6b1a4

    
           # Will add a route to the Plezi application. 
        
           # 
        
           # The order of route creation is the order of precedence. 
        
           # 
        
           # path:: the HTTP path for the route. Inline parameters and optional parameters are supported. i.e. 
        
           # 
        
           #                Plezi.route '/fixed/path', controller 
        
           #                Plezi.route '/fixed/path/:required_param/(:optional_param)', controller 
        
           #                Plezi.route '/(:format)', /^(html|json|xml)$/ # a rewrite route, usally on top. 
        
           #                Plezi.route '*', controller # catch all 
        
           # 
        
           # 
        
           # controller:: A Controller class or one of the included controllers: `false` for rewrite routes; `:client` for the Javascript Auto Dispatch client; `:assets` for a missing asset baker controller (bakes any unbaked assets into the public folder file). 
        
           def route(path, controller)

... of course, these examples are incomplete, as they don't use the YARD keywords to indicate arguments and return values, but I guess you get the gist of it, and the examples are published automatically here.

Many Ruby projects would benefit from improved documentation. So this is a really important subject,

Again, thanks! 🙏🏻🙏🏻🙏🏻👏🏻👍🏻

	# Get / set the template folder for the {Controller#render} function.
	attr_accessor :templates

	# Will add a route to the Plezi application.
	#
	# The order of route creation is the order of precedence.
	#
	# path:: the HTTP path for the route. Inline parameters and optional parameters are supported. i.e.
	#
	# Plezi.route '/fixed/path', controller
	# Plezi.route '/fixed/path/:required_param/(:optional_param)', controller
	# Plezi.route '/(:format)', /^(html\|json\|xml)$/ # a rewrite route, usally on top.
	# Plezi.route '*', controller # catch all
	#
	#
	# controller:: A Controller class or one of the included controllers: `false` for rewrite routes; `:client` for the Javascript Auto Dispatch client; `:assets` for a missing asset baker controller (bakes any unbaked assets into the public folder file).
	def route(path, controller)

Documentation help needed.