Warnings for undocumented entities: feature request

[szaghi]

Hi Chirs,

During the porting of all my other Fortran codes from doxygen to Ford I have realized that it would be a very nice feature to have the possibility to activate a "verbose checking" that will advice for entities that Ford has recognized without a documentation. As an example, ford -warnall ... prompting to stdout something like paranoiac advice for undocumented entities.

file bar.f90

function ciccio(pinco) result(pallo)
implicit none
integer:: pinco ! not documented
logical:: pallo !! well documented
...
endfunction ciccio

Ford paranoiac mode

ford -warnall bar-project-file.md
...
warning: variable 'pinco' is not documented! line 3 of file bar.f90
...

[cmacmackin]

I've added this feature and pushed it to the Github repository. I don't plan to put out a new release for it (yet) though, as I'd prefer to have more than just one new feature before I do that (some bugfixes at least). The command-line syntax is -w or --warn to produce the warning messages. Alternatively, placing "warn: " in your project meta-data will do the same thing, so long as some character follows the colon. Unfortunately, there is no easy way to allow it to provide a line number (sorry about that, I realize it would have been useful). Maybe a feature for some other time.

[szaghi]

Great Chris.

Don't worry about line number, the warn on name of entity is enough! I will try it late in the morning. Thanks.

[szaghi]

Just tested... works great! But there is something that is not well documented...

Let us consider IR_Precision module. The latest ford in warn mode tell me

...
Warning: Undocumented variable MinR16P in file IR_Precision.f90
...

As you can see here the variable is really not documented by Ford, but it has its "own" docstring, see this line 98.

I guess that the problem is due to my bad attitude to use one docstring for more than one variables (that are grouped being similar in some ways). As a matter of fact, line 98 defines two variables, namely MinR16P and MaxR16P, but the docstring is associated only to the last defined variable.

I suppose that it is very difficult to allow many variables sharing the same docstring, this is just a remainder.

Thank you very much for great work.

[cmacmackin]

This is intended behaviour. When multiple variables are declared on one
line (including the case when line continuations are used), only the
last one will have any documentation associated with it. Other
autodocumentation software seems to have similar behaviour. I must say
that I never really anticipated having one docstring associated with two
separate variables. I don't intend to change this, as it would entail
breaking the API.

On 27/01/15 06:41 AM, Stefano Zaghi wrote:

Just tested... works great! But there is something that is not well
documented...

Let us consider IR_Precision module. The latest ford in warn mode tell me

...
Warning: Undocumented variable MinR16Pin file IR_Precision.f90
...

As you can see here
http://szaghi.github.io/IR_Precision/module/ir_precision.html#var-MinR16P
the variable is really not documented by Ford, but it has its "own"
docstring, see this
https://github.com/szaghi/IR_Precision/blob/master/src/IR_Precision.f90
line 98.

I guess that the problem is due to my bad attitude to use one
docstring for more than one variables (that are grouped being similar
in some ways). As a matter of fact, line 98 defines two variables,
namely |MinR16P| and |MaxR16P|, but the docstring is associated only
to the last defined variable.

I suppose that it is very difficult to allow many variables sharing
the same docstring, this is just a remainder.

Thank you very much for great work.

—
Reply to this email directly or view it on GitHub
https://github.com/cmacmackin/ford/issues/25#issuecomment-71624778.

Chris MacMackin
Saint Mary's University
Curriculum Vitae http://ap.smu.ca/%7Ecmacmack/CV.pdf

[szaghi]

Sure, I agree with you.

This is just a remark for eventual, future improvement.

Thank you again.

[szaghi]

Hi Chris,

I have found a possible "false" positive warning.

In FLAP the type bound procedures (e.g. free or check) have their own docstring (e.g. see free one). However, Ford complains with them giving me:

|stefano@zaghi|0|02:26 PM Tue Jan 27|
|~/fortran/FLAP|10 files, 92Kb|
|->~/python/ford/ford.py -w doc/main_page.md 
Reading file ./src/IR_Precision.f90
Reading file ./src/flap_test.f90
Reading file ./src/Lib_Strings.f90
Reading file ./src/Data_Type_Command_Line_Interface.f90
Reading file ./src/Lib_IO_Misc.f90

Warning: Undocumented boundprocedure free in file Data_Type_Command_Line_Interface.f90
Warning: Undocumented boundprocedure check in file Data_Type_Command_Line_Interface.f90
...

Have I done a mistake in documenting the type bound procedure, line 701?

[cmacmackin]

Okay, this is actually fairly subtle. For bound procedures and module
procedures there are effectively two layers of documentation. One is in
the procedure itself, while the other is where the bound/module
procedure is declared as such. The warning message is complaining that
you haven't documented the latter case.

On 27/01/15 09:36 AM, Stefano Zaghi wrote:

Hi Chris,

I have found a possible "false" positive warning.

In FLAP the type bound procedures
http://szaghi.github.io/FLAP/type/type_command_line_interface.html
(e.g. free or check) have their own docstring (e.g. see free
http://szaghi.github.io/FLAP/proc/free.html one). However, Ford
complains with them giving me:

|stefano@zaghi|0|02:26 PM Tue Jan 27|
|/fortran/FLAP|10 files, 92Kb|
|->/python/ford/ford.py -w doc/main_page.md
Reading file ./src/IR_Precision.f90
Reading file ./src/flap_test.f90
Reading file ./src/Lib_Strings.f90
Reading file ./src/Data_Type_Command_Line_Interface.f90
Reading file ./src/Lib_IO_Misc.f90

Warning: Undocumented boundprocedure freein file Data_Type_Command_Line_Interface.f90
Warning: Undocumented boundprocedure checkin file Data_Type_Command_Line_Interface.f90
...

Have I done a mistake in documenting the type bound procedure
https://github.com/szaghi/FLAP/blob/master/src/Data_Type_Command_Line_Interface.f90,
line 701?

—
Reply to this email directly or view it on GitHub
https://github.com/cmacmackin/ford/issues/25#issuecomment-71648139.

Chris MacMackin
Saint Mary's University
Curriculum Vitae http://ap.smu.ca/%7Ecmacmack/CV.pdf

[szaghi]

Ok, now it is more clear.

The warnings disappear if the type bound procedure have their own docstrings also into the contains specification.

Thank you Chris.