Documenting $scope properties

[Nate-Wilkins]

I'm currently using docular to document our JavaScript modules and our AngularJS components. However I've had a tough time dealing with the repetitive nature that docular forces on the developer. ex.

@doc Property
@propertyOf ns:myObj
@name ns:myObj#myProperty

But now my real problem is documenting angular controllers with the ngdoc type controller

/**
 * @ngdoc Controller
 * @name ns:MyCtrl
 * @description A description
 */
angular.module('app').controller('MyCtrl', function ($scope) { 

    /**
     * @ngdoc Property
     * @name ns:Myctrl#myProperty
     * @description A description
     */
    $scope.myProperty = 42;

});

Documentation on docular is a little rough in spots. Might send a PR if I can understand it more.

[vincentdieltiens]

If I understand well, you want to documentate $scope properties ?
For what purpose ?

I think that not everything in a code needs to be documented.
Documentation is for people who is writing code that interact with yours :

• your code is a library
• for internal use : remember how to use a component

In case of scope properties, they are private to the scope. I don't the see the purpose of documenting those, because you should never access it outside the controller (or the template of the controller)

[Nate-Wilkins]

I'm talking directives mostly. Although on occasion a sub controller/template pair would need to be documented.

I do agree that not everything needs to be documented and am a big believer in self documenting code but this is not a project that persists of just myself. It's a pretty big project with a multitude of developers that need to know how to use certain components internally that they didn't make but have to use.

Documenting what's on $scope would be very helpful for directive components for a dev guide. Although maybe only the 'localized' scope properties set on the directive should be documented (ideally)