Generate documentation for your packages with Endokken


#1

I strongly believe that documentation makes a huge difference in whether a project succeeds or fails. This is one of the reasons why I enjoy working with Ruby so much, because of the copious documentation that is easily generated by YARD. But although there are documentation tools available for Atom itself, there hasn’t been an end-to-end documentation tool like YARD for Atom packages. Until now …

Endokken is a Node.js module that you can use to easily generate static HTML documentation from your AtomDoc code documentation comments. Just call endokken from the root directory of your Atom package and it will generate documentation in the docs directory. You can then open docs/README in the browser of your choice and navigate using the table-of-contents on the left.

I hope to have a sample site up soon to showcase my packages and their documentation generated by Endokken.

This is the first real Node.js module I’ve written, so feedback is welcome either here or on the Endokken issues page!


Use atomdoc in my own Project?
#2

Is it possible to document instance properties that are defined using Object.defineProperty?

I can document a normal instance property, documentation is generated for property1 in the below code. But I can’t figure out how to generate documentation for the properties (property2 and property3) that are defined using Object.defineProperty.

I’ve tried to alternative methods of defining such a property below, but neither generates any documentation. Is there some other pattern that’s the document generator does recognize?

Function::property = (prop, desc) ->
  Object.defineProperty @prototype, prop, desc

class Test

  # Public: Property one
  property1: null

  # Public: Property two
  @property 'property2',
    get: -> @_id

  # Public: Property three
  Object.defineProperty @::, 'property3', get: ->

Thanks,
Jesse


#3

No, currently only the property1 style is supported. The others may be added in the future, but they’ll need to be added upstream in donna and tello also.


#4

Thanks for the links.

It looks like donna is parsing out get/set properties and documentation with the parser if you use the format:

class Test

  get = (props) => @::__defineGetter__ name, getter for name, getter of props
  set = (props) => @::__defineSetter__ name, setter for name, setter of props

  # Public: 
  get testProp: -> @_testProp
  set testProp: (@_testProp) ->

But then in Metadata.generate that info gets lost somehow. Unfortunately, I’ve run out of time at the moment. But it does look like there’s already significant progress on this.

Edit Never mind, it’s not getting lost… I’ll report back when I really understand what’s happening.


#5

Looks again like this info is present in donna, but might be getting lost when metadata is generated. I’ve created an issue here: https://github.com/atom/donna/issues/6


#6

I tried to hack a bit into donna, but didn’t have time to really understand that code and what it’s done. Instead I found this messy but effective hack for documenting getters and setters:

# Public: Document a standard instance variable (which current documentation does understand. And then overwrite that will whatever form of getter/setter syntax you want to use.
testProp: null
get testProp: -> @_testProp
set testProp: (@_testProp) ->

So from my original example you can do this:

Function::property = (prop, desc) ->
  Object.defineProperty @prototype, prop, desc

class Test

  # Public: Property one
  property1: null

  # Public: Property two
  property2: null
  @property 'property2',
    get: -> @_id

  # Public: Property three
  property3: null
  Object.defineProperty @::, 'property3', get: ->