API documentation and use-case examples [JOSS #5072]

[mlxd]

Hello, I am currently reviewing the library for as part of openjournals/joss-reviews#5072

I see that several PDFs have been added to showcase the library (as in the following link). Though, I think the API-level documentation and overall guides are lacking for a developer to explore and use the library effectively.

Is there a plan to create a project-based site with a searchable API (Github pages, read-the-docs, etc), with guidelines and examples for usage? The linked PDF shows some detail, but this would be better served as part of a markdown (or equivalent) doc and linked to the front-level README.md for developers.

I think considering some like a doxygen-compatible CPP file headers and auto-generated API docs would also be beneficial here, for generating user-facing API docs throughout the repository.

[Ravenwater]

I have added a markdown one pager in docs and also added a segment to the readme that explains the broad structure of the parameterization. Since these are plug-in replacement types for native arithmetic types, the constructor is the only API that is explicit, the main use cases are implicit in the form of arithmetic and conversion expressions.

…

On Tue, Feb 7, 2023, 17:42 mlxd ***@***.***> wrote: Hello, I am currently reviewing the library for as part of openjournals/joss-reviews#5072 <openjournals/joss-reviews#5072> I see that several PDFs have been added to showcase the library (as in the following link <https://github.com/stillwater-sc/universal/blob/8230030258521adbce0f72ecb52ae560d499a75f/docs/presentations/fptalks-custom-number-systems.pdf>). Though, I think the API-level documentation and overall guides are lacking for a developer to explore and use the library effectively. Is there a plan to create a project-based site with a searchable API (Github pages, read-the-docs, etc), with guidelines and examples for usage? The linked PDF shows some detail, but this would be better served as part of a markdown (or equivalent) doc and linked to the front-level README.md for developers. I think considering some like a doxygen-compatible CPP file headers and auto-generated API docs would also be beneficial here, for generating user-facing API docs throughout the repository. — Reply to this email directly, view it on GitHub <#325>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADR5UMHIFUZBWTYAAOOPMDWWLFW3ANCNFSM6AAAAAAUURHTWI> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>