Administrate: We should document the existance of `new_resource`

[nickcharlton]

In #1097, we refer to the new_resource method which is useful when building out new records in a controller. But it isn't referenced anywhere.

We might like to answer:

• What problem does it solve?
• How do you use it?

It'd be best if we added it to a "Customising Administrate" or "Internals" section, or similar.

[pablobm]

There are a few hooks in Administrate::ApplicationController that we don't document. Currently, the page Customizing controller actions is the closer we have, I think. This in turn is an outdated version of the directions included with automatically generated controllers: https://github.com/thoughtbot/administrate/blob/master/lib/generators/administrate/dashboard/templates/controller.rb.erb

I think we have two problems regarding documentation of our APIs:

1. Documentation out of sync.
2. Not clear where to add documentation when anything is added.
3. Duplication (eg: doc page and generator).

An idea would be:

1. Annotate the API using RDoc or similar.
2. Use this to generate part of our documentation.
3. Replace other instance (eg: comments in generated code) with links to this documentation.

I think that would ease the three problems I list above. What do you think?

[nickcharlton]

Yeah, I agree with that. I've generally been a fan of YARD but I don't have very strong opinions on it.

[pablobm]

It's been very long since I used any of these tools, so I don't know the difference. Whichever is good for me!

[sedubois]

FYI a description of how the Rails documentation is generated: https://discuss.rubyonrails.org/t/api-rubyonrails-org-sidebar-rendering/74644/5

[pablobm]

I'm now realising I said "whichever is good for me", and I meant "whichever is good for you works for me", or something like that :sweat_smile: