Adds documentation

[gavD]

• New gulp task gulp ngdocs to generate documentation into build/docs
• Add ngdoc-compliant documentation to source code
• Add documentation to README.md
• Add Markdown version of docs in /docs directory

Test script

• Read the README.md documentation
  • Assert that it makes sense
  • Assert that it is correct in how it describes angular-model
    • For instance, I kind of refer to angular-model in terms of active record. Is that way off base?
• Read the API documentation
  • Assert that it makes sense
  • Assert that it is correct in how it describes angular-model
  • Assert that I have used ngdoc correctly
    • If you run gulp ngdoc then open a web server as per the instructions, I'm a bit confused as to why it seems to think the namespace us ur sometimes and ur.model other times.
      • Am I right to establish the model as an overview? gulp-ngdocs doesn't support modulecode
    • How should I be describing the model() function exactly? In terms of what @name should be

Script for generating Markdown docs

This script is scrappy but it works for now

# Create HTML docs
gulp ngdocs

# Convert to raw Markdown
pushd build/docs/partials/api
for f in *.html; do echo "Processing $f file..";  pandoc $f -f html -t markdown_github  -o ../../../../docs/${f/html/md}  ;  done
popd

# Mung Markdown together into a single file, ordered manually
pushd docs
echo "# angular-model API documentation\n\n" > api.tmp
cat ur.model.model.md ur.model.\$instance.md ur.model.\$class.md ur.model.\$collection.md ur.model.\$get.md \ur.model.directive.link.md >> api.tmp
rm *md
mv api.tmp api.md
sed -i .bak 's/ prettyprint/javascript/' api.md
rm api.md.bak
popd

Next steps

Once this is merged, we should:

• Tag
• Release to NPM (I will need John's help for this as I'm not certain how is best.)
• Merge this PR in angular-scaffold
• Blog post

[jfmercer]

Grunt? Don't you mean Gulp?

[jfmercer]

@gavD With the exception of the odd Grunt reference, everything looks fine to me. In fact, this is outstanding work. There are a few assertions that should be left for @nateabele. E.g., are you using ngDocs correctly? Well, I hope so.

Again, great work. 👍

[gavD]

Fixed the refs to Grunt. I've also added a PR which increases coverage to 95% - see #44 .

[nateabele]

Looks like copypasta from $revert(). $exists() checks whether an object exists in the API, based on whether it has an identity URL.

[nateabele]

I'm a bit confused as to why it seems to think the namespace us ur sometimes and ur.model other times.

References?

Am I right to establish the model as an overview?

Yup.

How should I be describing the model() function exactly?

Looks pretty good as-is. Maybe 'model definition class' if you want to get specific?

---

I made notes on the few issues I saw. Everything else looks 👍.

[gavD]

@nateabele thanks for the feedback :-) I have fixed all the issues you raised except for the one where I document @return statements.

[nateabele]

Merging this now. Also, Bower is lame and no one should use it anymore. All of its reasons for existing have been superseded by improvements in tools that are actually good.