ublas
ublas copied to clipboard
boostorg
Documentation for special functions of tensors added
I have added the documentation of special functions for tensors as instructed in proposal https://github.com/boostorg/ublas/discussions/167#discussioncomment-2166688
You just added the file special_functions.adoc, but there is no link to the file. Please, add the link in the index to access it. Otherwise, users will not know about it. It's like you created a function, and you never used it.
Furthermore, I would expect you to take some time and define each function properly without using a table. Each function to have its own section, where you define it, give the prototype, and examples using code blocks. Keep in mind to provide tensor specific behaviour, such as if a method is valid for static tensor or not, is there a tensor type-specific behaviour, etc.
Also, think about readability than concise or cryptic documentation. Put yourself in the shoes of a newbie, who doesn't know about the library that well, and how will (s)he react to the documentation, will it help them to understand it.
Hello, So for the first requirement i need to add the link of the files where all the special functions are used right? Also i will be giving explaination prototype and examples of each function using code blocks in some time, thanks for the suggestion.
Hello, So for the first requirement i need to add the link of the files where all the special functions are used right?
Read the existing document to see how to link the file or take help from @shikharvashistha.
I'm sharing a screenshot of what I meant. Don't let your ideas be clouded by what I'm sharing, and add something you think would be much better than what I'm suggesting. My top priority for documentation is "readability" and "the user does not have to read the codebase to figure out how's the library works."
Hello I have prepared the documentation for the special functions, I just wanted to ask that the code examples that needs to be added for each function should be taken from the codebase only right ? i.e from functions.hpp where they are implemented
Hello I have prepared the documentation for the special functions, I just wanted to ask that the code examples that needs to be added for each function should be taken from the codebase only right ? i.e from functions.hpp where they are implemented
Yes, you can also refer to the examples folder.