[Migrating from phpDocumentor to Natural Docs] #documentation #php #javascript

migrating-from-phpdocumentor-to-naturaldocs.md

Migrating from phpDocumentor to Natural Docs

Migrating to solve recurring technical issues in Travis build.

Natural Docs doesn't have the community support of phpDocumentor. While it works well, a voice inside my heads keeps screaming at me "but it's not best practice!" But I'm not sure that 'best practice' really applies to documentation, given that there are so few players in this field.

phpDocumentor

Pros

• supported by PHPCS, so can be used as a documentation linting tool

Cons

• consumes a lot of debugging time when it doesn't work
• cannot be upgraded past version 2.9.0 (which added support for php 7) due to version 3 being in alpha since 2017
• outdated dependencies create dependency clashes, blocking development

Natural Docs

Pros

• quick responses to logged Github issues
• fairly good documentation

Cons

Back ticks

• no support for back ticks, to style code in comments

Parameter types

• no support for parameter types (need to make explicit in code, this is possible in PHP but not JavaScript)

  // php
  /**
    	* Method: set_url
    	*
    	* Set the value of $url
    	*
    	* Parameters:
    	*   $new_url - New URL
    	*/
    	protected function set_url( string $new_url ) {
    		$this->url = $new_url;
    	}
  

Return types

• I can't specify a type for what the function returns, so I have to hack this into the description

  Returns:
    (string) foo - Bar baz
  

PHPCS

• no support in PHPCS, so cannot be used as a documentation linting tool, and causes errors to be generated by PHPCS:

PHP Code Sniffer found a problem in /home/travis/build/dotherightthing/wpdtrt-plugin-boilerplate/src/Plugin.php
    FILE: ...s/build/dotherightthing/wpdtrt-plugin-boilerplate/src/Plugin.php
    ----------------------------------------------------------------------
    FOUND 9 ERRORS AFFECTING 9 LINES
    ----------------------------------------------------------------------
     231 | ERROR | Doc comment for parameter "$composer_json" missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     281 | ERROR | Doc comment for parameter "$plugin_dependencies"
         |       | missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     385 | ERROR | Doc comment for parameter "$new_url" missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     409 | ERROR | Doc comment for parameter "$new_demo_shortcode_params"
         |       | missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     435 | ERROR | Doc comment for parameter "$new_prefix" missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     461 | ERROR | Doc comment for parameter "$new_slug" missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     486 | ERROR | Doc comment for parameter "$new_menu_title"
         |       | missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     511 | ERROR | Doc comment for parameter "$new_settings_title"
         |       | missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
     537 | ERROR | Doc comment for parameter "$new_developer_prefix"
         |       | missing
         |       | (Squiz.Commenting.FunctionComment.MissingParamTag)
    ----------------------------------------------------------------------
    
    Time: 391ms; Memory: 18MB

Not used to it yet

• relatively niche, so little support information on Stack Overflow
• compared to the phpDoc syntax, the 'natural' syntax feels a bit hacky; I suppose I initially found phpDoc a bit rigid, but have slowly gotten used to it

No markdown support

• Markdown syntax isn't supported:

  wrong:

  [my link](http://foo.com/bar)
  

  right:

  <my link: http://foo.com/bar>
  

Things that seemed like Cons but weren't

Comment block style

• comment blocks are different to the style I'm used to

  /* Function: foo
  ...
  */
  

  but through experimentation I've realised that I can keep doing it my way:

  /**
    * Function: foo
    */
  

Comment block whitespace

• the documented comment style contains a lot of whitespace:

  Parameters:
    
    foo - Foo
  
    bar - Bar
  
    baz - Baz
  

  but through experimentation I've realised that I can do this my way:

  Parameters:
    foo - Foo
    bar - Bar
    baz - Baz