Need Insight on Writing Plugin Documenation

Corona Marketplace Corona Community Plugins
#1

I’m working on my first plugin and have run into a small snag.

I have a library that generates an ‘object’ and I’m having a heck of a time modifying the plugin documentation template to properly document it.

To be clear, I’m releasing a module to ‘calculate collision filters based on named colliders’.  This snippet demonstrates it in action (excerpt from my plugin example):

-- EXCERPT TO AVOID UBER DUMP local rgcc = require "plugin.rgcc" local group = display.newGroup() -- .. physics setup not shown for brevity local createBall local myCC = rgcc.newCalculator() myCC:addNames( "block", "redBall", "greenBall" ) myCC:collidesWith( "redBall", "block", "greenBall" ) createBall = function( x, y, r, color, type) local tmp = display.newCircle( group, x, y, r ) tmp:setFillColor( unpack( color ) ) physics.addBody( tmp, "dynamic", { radius = r, friction = 0.2, bounce = 0.85, filter = myCC:getCollisionFilter( type ) } ) timer.performWithDelay( 1000, function() createBall(x, y, r, color, type) end ) end createBall( display.contentCenterX - 100, 30, 10, {1,0,0}, "redBall" ) createBall( display.contentCenterX + 100, 30, 10, {0,1,0}, "greenBall" )

If you read the code, you’ll see I have the plugin library ‘rgcc’.  This library has one function:

local myCC = rgcc.newCalculator()

When the above function is called, it produces a table object (myCC) with a number of methods attached to it, including:

  • addName()
  • addNames()
  • collidesWith()
  • getCategoryBits()
  • getMaskBits()
  • getCollisionFilter()
  • dump()

The Problem

The problem is, that I can figure out how to document the newCalculator() function:

  1. Duplicate FUNCTION.markdown (from docs template)
  2. Renamed it to newCalculator.markdown
  3. Fill it in as per directions.
  4. Refer to it from Readme.markdown

But I’m stumped on how to link to and document:

  • myCC - i.e. The returned object
    • addName()
    • addNames()
    • collidesWith()
    • getCategoryBits()
    • getMaskBits()
    • getCollisionFilter()
    • dump()

Partial Solution

I’m considering grabbing markdown code from Readme.markdown and using it in newCalculator.markdown like this:

### Functions ##### [myCC:addName()](addName.markdown) ##### [myCC:addNames()](addNames.markdown) ... ##### [myCC:dump()](dump.markdown)

Then, for each referenced function I’ll copy a FUNCTION.markdown, rename it, and fill it in.

Missing Part of Solution

The only issue is I won’t have a Return value link at the top of newCalculator.markdown.  i.e. Although a value is returned, I don’t know how link and document it.

Plan

First, if you’ve read this far you’re awesome.  Thanks for bearing with me.

Right now, I plan on following the above solution steps.  I’ll then submit and if adjustments are needed for the docs, I’ll work with a contact then.

That said, if anyone has dealt with this already, please share your thoughts and a solution if you have one.

Cheers,

Ed

#2

Hey Ed,

I’ll be your contact for the store submission when you get to that point. Don’t sweat following the template exactly. It’s there to help you, it’s a tool for you. If the tool doesn’t fit the task, make or get a new tool. Take a look at Jason’s Twitter plugin documentation. It doesn’t follow the mold exactly, but it is still a good reference. But, your partial solution is the way we planned it. See instructions in that repository.

Let’s take a look at some analogous Corona docs. Our Particle System has functions, inherited properties, and so on.  The core of feature  is the physics.newParticleSystem(), which returns a ParticleSystem object. Your readme.markdown should introduce your plugin, tell users how to include it in their projects (build.settings, etc.), and start introducing APIs maybe have a change log, etc. It’s the front page of your docs.

So, your plugin exposed features should go on the readme. You should say that newCalculator returns a Calculator object. On that object’s markdown page, you define its various properties and functions. I think what you’re missing is the markdown page for the object?

If there are any suggestions as to how to improve the template, let me know – or submit a pull request on the repo.

Hope that helps! Not sure I understood the question this frazzled Friday evening.

  • Michael

P.S. If you’re having issues with the markdown format, there’s a great live markdown previewer plugin for sublime.

#3

@Michael,

Thanks for the reply and the link to the previewer.  That will help a lot.  

You did understand my question just fine.  I’m afraid I had trouble asking it intelligently (same prob…hey it’s Friday night…what the heck am I doing coding and documenting!?)

Cheers,

Ed

#4

Because that’s how things get done. :slight_smile:

I’m used to my own doc style, I’ve just been building it up in a wiki in markdown, then I can move / convert as needed. I was told that the template was not required, just docs in a useful format. My issue is testing, but that’s for another thread.

Cheers.

#5

Hey Ed,

I’ll be your contact for the store submission when you get to that point. Don’t sweat following the template exactly. It’s there to help you, it’s a tool for you. If the tool doesn’t fit the task, make or get a new tool. Take a look at Jason’s Twitter plugin documentation. It doesn’t follow the mold exactly, but it is still a good reference. But, your partial solution is the way we planned it. See instructions in that repository.

Let’s take a look at some analogous Corona docs. Our Particle System has functions, inherited properties, and so on.  The core of feature  is the physics.newParticleSystem(), which returns a ParticleSystem object. Your readme.markdown should introduce your plugin, tell users how to include it in their projects (build.settings, etc.), and start introducing APIs maybe have a change log, etc. It’s the front page of your docs.

So, your plugin exposed features should go on the readme. You should say that newCalculator returns a Calculator object. On that object’s markdown page, you define its various properties and functions. I think what you’re missing is the markdown page for the object?

If there are any suggestions as to how to improve the template, let me know – or submit a pull request on the repo.

Hope that helps! Not sure I understood the question this frazzled Friday evening.

  • Michael

P.S. If you’re having issues with the markdown format, there’s a great live markdown previewer plugin for sublime.

#6

@Michael,

Thanks for the reply and the link to the previewer.  That will help a lot.  

You did understand my question just fine.  I’m afraid I had trouble asking it intelligently (same prob…hey it’s Friday night…what the heck am I doing coding and documenting!?)

Cheers,

Ed

#7

Because that’s how things get done. :slight_smile:

I’m used to my own doc style, I’ve just been building it up in a wiki in markdown, then I can move / convert as needed. I was told that the template was not required, just docs in a useful format. My issue is testing, but that’s for another thread.

Cheers.