This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
By default the source folder is used as the --source option for ApiGen. However when someone uses some framework and other libraries in their project they might want to use them for generating the API documentation as well. Basically everything that NetBeans use for code hinting etc. should be available to ApiGen. That means that all directories in the Include Path should be used as --source options as well. It might be a subject of further discussion if such libraries should be fully documented or (automatically) skipped using the --skip-doc-path option so that they will only serve as sources of inherited methods/properties/... and would appear in the class tree.
Feel free to suggest any solution that will work for most of the users. Thanks.
Closing as INCOMPLETE and waiting for you since you are definitely more appropriate person to suggest a solution for this issue. Simply reopen this issue, thanks.
We have proposed a solution in the first comment. Both source folders and libraries should be passed to ApiGen via --source. That would be the simple way for the beginners. Both the project sources as well as libraries would appear in the documentation, A more advanced way would be to pass library folders via --skip-doc-path as well. That would still take them into consideration when generating the documentation (inherited methods would be visible for example) but classes/... from libraries would not have their own pages with documentation. What do you think?
(In reply to comment #3) > Both source folders and libraries should be passed to ApiGen via --source. > > That would be the simple way for the beginners. Both the project sources as > well as libraries would appear in the documentation, That will not work, at least for me since I have 7119 PHP files on my PHP include path (/usr/share/php). I definitely don't want to document them for every project every time. > A more advanced way would be to pass library folders via --skip-doc-path as > well. That would still take them into consideration when generating the > documentation (inherited methods would be visible for example) but classes/... > from libraries would not have their own pages with documentation. This sounds much better to me. Please notice that we have the same functionality (via PhpDoc) for about 2 or 3 years, we generate documentation only for project sources; till now, we do not have any issue against this behaviour. Therefore I prefer the solution with --skip-doc-path (for libraries). Thanks.
After a discussion here in the ApiGen team :) we agree that it is not wise to put the library path to --source as well. It would have its benefits but more likely it would cause problems. Using --skip-doc-path it wouldn't get documented BUT it still would get processed with all consequences (like throwing an exception when two or more classes have the same name). And in your case it would be very slow and memory consuming. Considering that we believe that an advanced user will have an own config file we are still talking about a feature that is aimed at beginners. And documenting just the source folder will be OK for them.
So, if I understand correctly, we can close this issue since there is nothing to fix here, right? If I have overlooked something, please reopen. Thanks.