Documentation refactoring tracker

[Syntaf]

This list serves to track most of the warnings generated by our documentation builder. Most of these have very simple resolutions( undocumented features ), so while the list looks big it's not all that much of an issue.

hpx/hpx_fwd.hpp
- [ ] line 836: parameters undocumented: binary_filter_type, compress, next_filter

hpx/lcos/when_all.hpp

• line 73: param futures not found in argument list
• line 71: param futures not found in argument list
• line 71: values argument is not documented

hpx/lcos/when_some.hpp

• line 21: member indices is not documented

hpx/runtime/actions/plain_actions.hpp

• line 106: symbol set not declared or defined

hpx/runtime/parcelset_fwd.hpp

• line 31: member get_message_handler is not documented
• line 36: member do_background_workd is not documented

hpx/runtime/runtime_mode.hpp

• line 34: member get_runtime_mode_from_name is not documented

hpx/runtime/threads/thread_enums.hpp

• line 66: member thread_state is not documented
• line 85: member thread_state_ex is not documented
• line 90: member thread_stacksize is not documented
• line 45: member get_thread_state_name is not documented
• line 68: member get_thread_priority_name is not documented
• line 102: member get_stack_size_name is not documented

hpx/runtime/threads_fwd.hpp

• line 102: member get_stack_size_name is not documented
• line 105: fifo_priority_queue_scheduler is not documented
• line 120: member queue_scheduler is not documented

hpx/runtime/runtime_mode.hpp

• line 34: member get_runetime_mode_from_name is not documented

hpx/runtime/components/colocating_distribution_policy.hpp

• line 199: member apply is not documented
• line 230: member apply_cb is not documented

hpx/runtime/components/default_distribution_policy.hpp

• line 233: member apply is not documented
• line 255: member apply_cb is not documented

hpx/parallel/executors/executor_parameter_traits.hpp

• line 219: param 'exec' is not in the argument list

hpx/parallel/executors/executor_parameter_traits.hpp

• line 153: executor_parameter_traits is not documented

docs/manual/lcos.qbk

• line 141: line breaks generate invalid boostbook

[VARUN-009]

I wanna work on this issue. Please assign this to me and since I'm new to this repo so I request you to please guide me through

[hkaiser]

I wanna work on this issue. Please assign this to me and since I'm new to this repo so I request you to please guide me through

@VARUN-009 Sure, please feel free to work on the missing documentation pieces. Please coordinate with @dimitraka as she is currently owning the documentation.

[dimitraka]

@VARUN-009 If you are interested in this, I would suggest that you first build the docs to see which of the warnings you can easily resolve. Since this issue was created in 2015, some warnings may be different as we have resolved some already.

[vivekd01]

i want to work on this issues please assignees me this issue

[dimitraka]

i want to work on this issues please assign me this issue

hey, @vivekd01! If you are interested in resolving the warnings of the documentation build process, you can start by building our docs and finding out which warnings exist at the moment. Then you can start resolving them step by step.

[ndjenks]

Hallo everyone, I am interested in working on this issue. I don't know if the there is a new status update concerning this issue ? Please what do you mean by "building our docs" ?

[ndjenks]

The list of files for this ticket seem to be outdated. Some files I can not find anymore in the current state of the project. Are they some plans to update the information of this ticket.

[hkaiser]

The list of files for this ticket seem to be outdated. Some files I can not find anymore in the current state of the project. Are they some plans to update the information of this ticket.

I can try doing this. Which files are you referring to?

[ndjenks]

• hpx/libs/full/checkpoint/include/hpx/checkpoint/checkpoint.hpp
• hpx/libs/full/distribution_policies/include/hpx/distribution_policies/unwrapping_result_policy.hpp
• hpx/libs/full/distribution_policies/include/hpx/distribution_policies/binpacking_distribution_policy.hpp
• hpx/libs/full/distribution_policies/include/hpx/distribution_policies/colocating_distribution_policy.hpp
• hpx/libs/full/distribution_policies/include/hpx/distribution_policies/default_distribution_policy.hpp
• hpx/libs/full/distribution_policies/include/hpx/distribution_policies/unwrapping_result_policy.hpp
• hpx/libs/full/distribution_policies/include/hpx/distribution_policies/target_distribution_policy.hpp
• hpx/libs/full/async_distributed/include/hpx/async_distributed/promise.hpp
• hpx/libs/full/async_distributed/include/hpx/async_distributed/base_lco.hpp
• hpx/libs/full/async_distributed/include/hpx/async_distributed/packaged_action.hpp
• hpx/libs/full/async_distributed/include/hpx/async_distributed/base_lco_with_value.hpp
• hpx/libs/full/async_distributed/include/hpx/async_distributed/packaged_action.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/counters.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/counters_fwd.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/registry.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/counters.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/counters_fwd.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/registry.hpp
• hpx/libs/full/performance_counters/include/hpx/performance_counters/counter_creators.hpp
• hpx/libs/full/naming_base/include/hpx/naming_base/unmanaged.hpp
• hpx/libs/full/segmented_algorithms/include/hpx/parallel/segmented_algorithms/exclusive_scan.hpp
• hpx/libs/full/segmented_algorithms/include/hpx/parallel/segmented_algorithms/transform_exclusive_scan.hpp
• hpx/libs/full/segmented_algorithms/include/hpx/parallel/segmented_algorithms/transform_inclusive_scan.hpp
• hpx/libs/full/plugin_factories/include/hpx/plugin_factories/binary_filter_factory.hpp
• hpx/libs/full/init_runtime/include/hpx/hpx_init_params.hpp
• hpx/libs/full/init_runtime/include/hpx/hpx_start.hpp
• hpx/libs/full/runtime_components/include/hpx/runtime_components/component_registry.hpp
• hpx/libs/full/agas_base/include/hpx/agas_base/server/primary_namespace.hpp
• hpx/libs/full/agas/include/hpx/agas/addressing_service.hpp
• hpx/libs/full/checkpoint_base/include/hpx/checkpoint_base/checkpoint_data.hpp
• hpx/libs/full/executors_distributed/include/hpx/executors_distributed/distribution_policy_executor.hpp
• hpx/libs/full/collectives/include/hpx/collectives/reduce_direct.hpp
• hpx/libs/full/collectives/include/hpx/collectives/communication_set.hpp
• hpx/libs/full/collectives/include/hpx/collectives/broadcast.hpp
• hpx/libs/full/collectives/include/hpx/collectives/scatter.hpp
• hpx/libs/full/collectives/include/hpx/collectives/channel_communicator.hpp
• hpx/libs/full/collectives/include/hpx/collectives/all_gather.hpp
• hpx/libs/full/collectives/include/hpx/collectives/gather.hpp
• hpx/libs/full/collectives/include/hpx/collectives/all_to_all.hpp
• hpx/libs/full/collectives/include/hpx/collectives/reduce.hpp
• hpx/libs/full/collectives/include/hpx/collectives/exclusive_scan.hpp
• hpx/libs/full/collectives/include/hpx/collectives/all_reduce.hpp
• hpx/libs/full/collectives/include/hpx/collectives/inclusive_scan.hpp
• hpx/libs/full/actions_base/include/hpx/actions_base/basic_action.hpp
• hpx/libs/full/actions_base/include/hpx/actions_base/lambda_to_action.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/runtime_fwd.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/server/runtime_support.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/stubs/runtime_support.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/applier.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/runtime_support.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/stubs/runtime_support.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed.hpp
• hpx/libs/full/runtime_distributed/include/hpx/runtime_distributed/server/runtime_support.hpp
• hpx/libs/full/components_base/include/hpx/components_base/server/migration_support.hpp
• hpx/libs/full/components_base/include/hpx/components_base/server/managed_component_base.hpp
• hpx/libs/full/components_base/include/hpx/components_base/server/fixed_component_base.hpp
• hpx/libs/full/components_base/include/hpx/components_base/get_lva.hpp
• hpx/libs/full/components_base/include/hpx/components_base/components_base_fwd.hpp
• hpx/libs/full/components_base/include/hpx/components_base/server/migration_support.hpp
• hpx/libs/core/async_base/include/hpx/async_base/launch_policy.hpp
• hpx/libs/core/cache/include/hpx/cache/statistics/local_statistics.hpp
• hpx/libs/core/cache/include/hpx/cache/statistics/no_statistics.hpp
• hpx/libs/core/cache/include/hpx/cache/local_cache.hpp
• hpx/libs/core/cache/include/hpx/cache/lru_cache.hpp
• hpx/libs/core/cache/include/hpx/cache/entries/entry.hpp
• hpx/libs/core/cache/include/hpx/cache/entries/fifo_entry.hpp
• hpx/libs/core/algorithms/include/hpx/parallel/container_algorithms/remove_copy.hpp
• hpx/libs/core/algorithms/include/hpx/parallel/algorithms/transform_reduce.hpp
• hpx/libs/core/algorithms/include/hpx/parallel/algorithms/transform_inclusive_scan.hpp
• repos/hpx/libs/core/functional/include/hpx/functional/mem_fn.hpp

The list is longer. I think there should be a better way to report the files here in Github. Do you know how I can do that? :)

[hkaiser]

I think we should not blindy add documentation across all files. We're trying to define a stable HPX API, currently and this is what we should add documentation for. There are other tickets attempting to define such an API, but there is no cosistent list (at least for the distributed API) yet. @dimitraka might have a better understanding what's missing.

[dimitraka]

@ndjenks if you would like to work on resolving the warnings your best start would be to build yourself the documentation (this means build hpx with documentation on) and see which warnings are generated now. Then, depending on the warning, we can find a solution. Some warnings are very simple to fix (for example typos), some other need some discussion.

Reference for building hpx can be found here https://hpx-docs.stellar-group.org/latest/html/manual/building_hpx.html and https://hpx-docs.stellar-group.org/latest/html/contributing/documentation.html

[ndjenks]

Thanks for the response. I followed the instructions in these files but I receive so many warnings(see list above). Am I doing something wrong ?

I have the cmake option -DHPX_WITH_DOCUMENTATION=ON.

[dimitraka]

@ndjenks yes this is correct.

If you didn't get any errors during the build process, then everything should be ok. You should be able to see the html files that were locally generated too.

It is indeed true that we have a lot of warnings :)

[ndjenks]

Happy to see that I am on the right track. I might suggest that we update the issue with the new warnings. What do you think @dimitraka ?

I will like to be assigned to this issue and might definitely need some help getting this job done.

[dimitraka]

@ndjenks Nice to hear that you would like to work on this. You can already get started :)

I don't think that there is a point in listing all the warnings here because this is a long list and these also may change during the documentation development. But let's see also what @hkaiser thinks about it.

In any case, I suggest you start working on this (since you are interested) and feel free to ask if you have any questions!