how to documents variables inside functions via phpDoc

Question

I am using PHPDoc standards for commenting PHP(laravel) code and ApiGen to generate an API Documentation.

I know that there are many Tags that can be used to present information.

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables can all be documented.

But now I want to document variables that are in a function.
for example suppose I have a function like this :

         /**
         * @param Request $request
         * @param         $course_id
         * @param         $lesson_id
         * @param Content $content
         *
         * @return array
         *
         */
        public function SaveOnePageTest (Request $request, $course_id, $lesson_id, \App\Content $content)
        {
            /**
            *I want to document this variable that how does this and What used to be?
            */

            $doneTest = DoneTest::find($done_test_id);

            /**
            *or this variable 
            */
            $parentQuestions = $doneTest->parent_test->questions;
        }

Is there a solution to this case?

There's no "formalised" approach to this, you simply add whatever comments you want — Mark Baker
– Mark Baker, Commented Jul 18, 2016 at 8:22
use simple comments can not create any information about variables inside functions in final API documentation. — Ahmad Badpey
– Ahmad Badpey, Commented Jul 18, 2016 at 8:29
No it can't, but why should any end user need to know about the internals of a method? — Mark Baker
– Mark Baker, Commented Jul 18, 2016 at 9:06
@Mark Baker, no i do not need that end user to know internal method, I want it for me and my contributors. in fact I do not know other companies use which tools to code maintenance — Ahmad Badpey
– Ahmad Badpey, Commented Jul 18, 2016 at 13:56
As you and the contributors should have direct access to the code, then there's surely no issue with simply commenting the code itself. Tools like PHPDoc and ApiGen are for documenting the end-user interfaces to the class/methods/properties, not internal code values — Mark Baker
– Mark Baker, Commented Jul 18, 2016 at 14:04

n00dl3 · Accepted Answer · 2022-01-14 11:10:15Z

3

this kind of documentation tool/syntax have been developed to help people consuming a library/a software API.

Local variables are not accessible to the end user so there is no real need to expose them in the documentation.

While you can document your inner code, there is no standard way to do this using PHPDoc.

Update : Note that You can use phpdoc to define the type of a variable in order to get better code completion, but that will not be part of the API documentation :

/** @var SomeType $someVar */
$someVar = $this->doSomething();

edited Jan 14, 2022 at 11:10

answered Jul 18, 2016 at 8:30

n00dl3

21.6k8 gold badges70 silver badges77 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

Ahmad Badpey Over a year ago

However, are not there any ways to document local variables? Why so I am working on large project and I want to create a documentation for that to remember that classes , variables , methods , ... what do ?

n00dl3 Over a year ago

just use regular comment for local variables, if someone needs to interact with local variable he will need to open the code whatever happen...

Collectives™ on Stack Overflow

how to documents variables inside functions via phpDoc

1 Answer 1

2 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Related