How would one go about documenting a constant using ngDoc? I don't see any angular specific documentation for documenting values registered with .constant, and the jsDoc syntax for constants doesn't seem to generate any actual docs when it's run through ngDoc.
Ex:
/**
* #constant
* #name WHITE
*
* #description
* The color white!
**/
module.constant( 'WHITE', '#fff' );
ngDocs currently doesn't provide a way to document constants. As you can see in its templating source code. There isnt relevant html_usage_* method.
I document constants like this, it shows a APP_CONFIG as a module then.
/**
* #ngdoc object
* #name APP_CONFIG
* #description
* constant...
* #example
* APP_CONFIG is injectable as constant (as a service even to .config())
* <pre>
* (...) .config(function ($APP_CONFIG) {
* </pre>
*/
It should be #const
/** #const */ var MY_BEER = 'stout';
/**
* My namespace's favorite kind of beer.
* #const {string}
*/
mynamespace.MY_BEER = 'stout';
/** #const */ MyClass.MY_BEER = 'stout';
/**
* Initializes the request.
* #const
*/
mynamespace.Request.prototype.initialize = function() {
// This method cannot be overridden in a subclass.
};
See the constant part http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml#Constants and the comments part http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml?showone=Comments#Comments for more informations
Related
Given this
type LocationWeather = {
name: string;
temperature: number;
};
type IndexProp = {
savedLocationsWeather: LocationWeather[];
favoriteLocationWeather: LocationWeather;
};
function Index({ savedLocationsWeather, favoriteLocationWeather }: IndexProp)
What should the documentation look like?
My first approach was:
/**
* Home page displaying weather details of saved locations and favorite location
* #param {object} props Component props
* #param {LocationWeather[]} props.savedLocationsWeather Weather details of saved locations
* #param {LocationWeather} props.favoriteLocationWeather Weather details of favorite location
* #return {TSX.Element}
*/
But:
I'm not sure if that's the correct way to specify the Array type of savedLocationsWeather as in
* #param {Array} props.savedLocationsWeather Weather details of saved locations
I'm also not sure it's correct to specify LocationWeather as a jsdoc type, as in
* #param {Locationweather} props.favoriteLocationWeather Weather details of favorite location
Is there even such a thing as a TSX.Element type, as in
* #return {TSX.Element}
Finally, should I define PropTypes as done here
Laravel Orchid: How can the post entry in the database be retrieved from in the PostEditScreen.php?
In a function in the PostEditScreen.php, how can the entry in the database that is being referred to by the PostEditScreen be accessed?
Post::find($post.id) is not working.
Any help would be greatly appreciated.
/**
* Query data.
*
* #param Post $post
*
* #return array
*/
public function query(Post $post): array
{
// This will already be a record of your model.
}
Or you can do it explicitly
/**
* Query data.
*
* #param int $id
*
* #return array
*/
public function query(int $id): array
{
Post::find($id)
}
This is stated in the laravel documentation: https://laravel.com/docs/7.x/routing#route-model-binding
I have a complex query that is not based on any specific model table that I want to paginate output for. However laravel's built in pagination relies on models and tables. How can I paginate a collection and have the output match up with laravel's built in pagination output format?
I keep this in an app\Core\Helpers class so that I can call them from anywhere as \App\Core\Helpers::makePaginatorForCollection($query_results). The most likely place to use this is the last line of a controller that deals with complex queries.
In app/Http/Controllers/simpleExampleController.php
/**
* simpleExampleController
**/
public function myWeirdData(Request $request){
$my_unsafe_sql = '...';//never do this!!
$result = DB::statement(DB::raw($my_unsafe_sql));
return \App\Core\Helpers::makePaginatorForCollection($result);
}
In app\Core\Helpers.php or anywhere you like that auto loads.
/**
* This will match laravel's built in Model::paginate()
* because it uses the same underlying code.
*
* #param \Illuminate\Support\Collection $collection
*
* #return \Illuminate\Pagination\LengthAwarePaginator
*/
public static function makePaginatorForCollection(\Illuminate\Support\Collection $collection){
$current_page = (request()->has('page')? request()->page : 1) -1;//off by 1 (make zero start)
$per_page = (request()->has('per_page')? request()->per_page : config('api.pagination.per_page')) *1;//make numeric
$page_data = $collection->slice($current_page * $per_page, $per_page)->all();
return new \Illuminate\Pagination\LengthAwarePaginator(array_values($page_data), count($collection), $per_page);
}
/**
* Copy and refactor makePaginatorForCollection()
* if collection building is too slow.
*
* #param $array
*
* #return \Illuminate\Pagination\LengthAwarePaginator
*/
public static function makePaginatorForArray($array){
$collection = collect($array);
return self::makePaginatorForCollection($collection);
}
I am just starting to get to grip using grunt-ngdocs for my angular application and so far so good.
But I would now like to document some properties of another documented prperty in one of my controllers.
Consider the following code:
(function() {
'use strict';
/**
* #ngdoc controller
* #name app.mymodule.controller:MyController
* #description
* A Controller
*/
angular
.module('app.mymodule')
.controller('MyController', Controller);
Controller.$inject = ['someService', 'otherService', '$state'];
function Controller(someService, otherService, $state) {
/**
* #ngdoc property
* #name vm
* #propertyOf app.mymodule.controller:MyController
* #description
* A named variable for the `this` keyword representing the ViewModel
*/
var vm = this,
searchText;
vm.customerService = customerService;
vm.fetchCollection = fetchCollection;
vm.deleteCustomer = deleteCustomer;
initialise();
function initialise() {
//logic
}
/**
* #ngdoc
* #name fetchCollection
* #methodOf app.mymodule.controller:MyController
*
* #description
* Function to retrieve records from the backend service
* #example
* vm.fetchCollection(page, perPage);
* #param {int} page The number of the page of data to be retrieved
* #param {int} perPage The number of items per page to be retrieved
* #returns {object} The response object returned from a httpPromise
*/
function fetchCollection(page, perPage){
//logic
}
function deleteCustomer(model) {
//logic
}
})();
As you can see, I have some properties hanging off the vm variable which are typically references to functions defined in the controller.
Using the ngdocs\jsdocs documentation syntax above I can get the vm property to output in my documentation folder, but I am unsure how to document the properties of the vm object itself.
Is there a sensible or recommended way to do this? I did wonder about not documenting vm altogether and just document each of the vm.xxx separately, but I'm not so sure about this!
Thanks
It is not very clear in the documentation, but you have to use the hash in the name.
Try this.
/**
* #ngdoc property
* #name app.mymodule.controller:MyController#vm
* #propertyOf app.mymodule.controller:MyController
* #description
* A named variable for the `this` keyword representing the ViewModel
*/
I'm about to design an service which handles URL parameters in AngularJS. Currently I have two different kinds of parameters.
Single valued
¶m=myValue
Multi valued
¶m=lorem,ipsum,dolor
I'm not sure whether to implement a setter for both single and multi valued parameters.
/**
* Set parameter
*
* #param {string} name
* #param {string|array} values
* #param {boolean} multi
*/
setParam: function(name, value, multi) { }
Or if each type of parameter should get its own setter?
/**
* Set single valued parameter
*
* #param {string} name
* #param {string} value
*/
setSingleValuedParam: function(name, value) { }
/**
* Set multi valued parameter
*
* #param {string} name
* #param {array} values
*/
setMultiValuedParam: function(name, array) { }
Please note: This is pseudo-code and does not work!
Even the single one that you show is technically an array with a single element. So I would just implement the multi-valued one.
/**
* Set parameters
*
* #param {string} name
* #param {array} values
*/
setMultiValuedParam: function(name, array) { }
When the query comes, split it by , and there will be 0 or more parameters in the array.
FYI: Definitely include a possibility of 0 parameters, because even if your program does not call with 0, since this is a query parameter, someone else could just hit the URL directly.