[Asterisk-code-review] progdocs: Update Makefile. (asterisk[16])

[Alexander Traud]

Attention is currently required from: Kevin Harwell.
Alexander Traud has posted comments on this change. ( https://gerrit.asterisk.org/c/asterisk/+/17578 )

Change subject: progdocs: Update Makefile.
......................................................................


Patch Set 2:

(2 comments)

Commit Message:

https://gerrit.asterisk.org/c/asterisk/+/17578/comment/ab7d6b65_dc11849e 
PS2, Line 22: ASTERISK-26991
> Is this fixing this issue, thus should close it? I believe the auto-close script just looks for ASTE […]
To answer your question: Yes, closing is intended.

Long answer:

ASTERISK-20259 did not fix all issues. Or more precisely, did a lot but was not finished, unfortunately. Now, with this change, I consider ASTERISK-20259 fixed, at least syntactically. Consistent style over all Doxygen comments and a birds-eye-view (semantically) is another story. Anyway, ASTERISK-26991 was about finding an alternative for the developer to get the Doxygen documentation. Now that ASTERISK-20259 is considered fixed, I think, the developer has a working alternative, especially because it is advertised after ‘make install’. And that closes ASTERISK-26991.

If I am not totally mistaken, the server http://doxygen.asterisk.org is not up anymore (since Sep. 2018) without replacement. So the problem about search-engine indexing is fixed as well. Finally, after going through the Doxygen comments, that documentation look (for me) more like API documentation. Therefore it is not targeted to normal users but API users, developers. And I consider those should be able to build the API documentation locally if they really need it.

Looking at what I said now, I am not sure about the advertisement after ‘make install’ anymore. Is that advertisement helpful? It might confuse normal users, not being API developers. Perhaps the wording should be changed from ‘program doc’ to ‘API doc’ and tell the user that the ‘usage doc’ was already built because of the XML documentation. What do you think? Perhaps even the whole make target should be removed and renamed to ‘apidoc’ or just ‘doxygen’ to be inline with the xml-doc which is a usage-doc actually.

By the way, https://doxygen.phreaknet.org has a current online copy.


File doc/.gitignore:

https://gerrit.asterisk.org/c/asterisk/+/17578/comment/f86886ca_60062445 
PS2, Line 5: asterisk-ng-doxygen
> Any reason to not just remove this?
Yes. The developer might still have it in its local copy, and then it would be uploaded after that change. I am not sure how to handle gitignore in Asterisk, being cumulative and avoiding any mistakes from past/future or list just current possible files. I opted for the former. If you like to have the latter, please, just say so. It was more like flipping-a-coin decision, keep it or drop it. I am fine with either way but had to make a decision. Therefore, I went for the more conservative approach in case of gitignore. With 'make distclean’, I went for the ‘opposite’.



-- 
To view, visit https://gerrit.asterisk.org/c/asterisk/+/17578
To unsubscribe, or for help writing mail filters, visit https://gerrit.asterisk.org/settings

Gerrit-Project: asterisk
Gerrit-Branch: 16
Gerrit-Change-Id: I4129092a199d5e24c319a09cd088614b121015af
Gerrit-Change-Number: 17578
Gerrit-PatchSet: 2
Gerrit-Owner: Alexander Traud <pabstraud at compuserve.com>
Gerrit-Reviewer: Friendly Automation
Gerrit-CC: Kevin Harwell <kharwell at digium.com>
Gerrit-Attention: Kevin Harwell <kharwell at digium.com>
Gerrit-Comment-Date: Wed, 01 Dec 2021 09:03:45 +0000
Gerrit-HasComments: Yes
Gerrit-Has-Labels: No
Comment-In-Reply-To: Kevin Harwell <kharwell at digium.com>
Gerrit-MessageType: comment
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.digium.com/pipermail/asterisk-code-review/attachments/20211201/eaf0d1d8/attachment.html>