Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document all capability atoms and profiles. #4125

Closed
csyonghe opened this issue May 7, 2024 · 2 comments · Fixed by #5008
Closed

Document all capability atoms and profiles. #4125

csyonghe opened this issue May 7, 2024 · 2 comments · Fixed by #5008
Assignees
@ArielG-NV
Labels
goal:quality & productivity Quality issues and issues that impact our productivity coding day to day inside slang kind:documentation areas where we can improve documentation in codebase
Milestone
Q3 2024 (Summer)

Comments

@csyonghe
Copy link
Collaborator

csyonghe commented May 7, 2024

We need a reference chapter in the user guide to document all supported capability atoms and their meanings.

Start a chapter at the end of user guide with the hierarchy "Reference -> Capability Profiles"
@bmillsNV bmillsNV added kind:documentation areas where we can improve documentation in codebase goal:quality & productivity Quality issues and issues that impact our productivity coding day to day inside slang labels May 9, 2024
@bmillsNV bmillsNV added this to the Q3 2024 (Summer) milestone May 9, 2024
@ArielG-NV ArielG-NV mentioned this issue Jul 22, 2024
Closed
@ArielG-NV ArielG-NV self-assigned this Jul 23, 2024
@ArielG-NV
Copy link
Contributor

ArielG-NV commented Jul 23, 2024 •
edited
Loading

Discussion from another issue about this topic:

@ArielG-NV , do we have a way to dump the name strings of profiles?
As far as I can see, there isn't a way to do it currently.

There currently is no way todo this.

Since there are a lot of profile names, I don't think we can list all of them on the document.
We should refer to a command-line option that can print out all the available profile name strings.

I believe we could do both options.

The idea I have in mind for documenting every capability/profile:

  1. inside tools\slang-capability-generator\capability-generator-main.cpp we could add logic to require a /// comment above the line of a capability definition.
  2. store this string inside slang\build\source\slang\capability\slang-generated-capability-defs-impl.h.
  3. Add build step to Slang (or CI) to autogenerate a user-doc with all capabilities using slang\build\source\slang\capability\slang-generated-capability-defs-impl.h.
  4. output the auto-generate code from '.3' as a a command-line output with slangc if slangc -help capabilities is added (or something similar)

@ArielG-NV ArielG-NV mentioned this issue Aug 12, 2024
Draft
@ArielG-NV ArielG-NV added the beyond-sprint Label for issues which will be worked on but not completed during a sprint. label Sep 3, 2024
@csyonghe
Copy link
Collaborator Author

csyonghe commented Sep 3, 2024

Parsing and storing the comments is a good idea, but for now let's just make sure the comments are in place first.

ArielG-NV added a commit that referenced this issue Sep 3, 2024
@ArielG-NV
Document All Capability Atoms and Profiles
05f5b83 
Fixes: #4125

Unimplemented Considerations:
1. This PR does not add support to query all capability-atom's from a command-line option. It is understood that this might be desired, due to this, the logic to generate `docs\user-guide\a3-02-reference-capability-atoms.md` was made to be "command-line friendly" so minimal changes are needed to pipe our documentation into a command-line option if this change is to be added.

Changes:
1. Added a way to document atoms inside `.capdef`. Method to document is described under `source\slang\slang-capabilities.capdef`. The goal is to error if a public atom does not have any form of documentation to ensure we always have up-to-date documentation to guide user on what an atom is/does.
    * The following `.capdef` file syntax was added
        * /// [HEADER_GROUP]
        * /// regular comment
2. When capability generator runs it auto-generates `docs\user-guide\a3-02-reference-capability-atoms.md`
3. Added to the user-guide 3 sections: `Reference`, `Reference -> Capability Profiles`, `Reference -> Capability atoms` section
ArielG-NV added a commit that referenced this issue Sep 3, 2024
@ArielG-NV
Document All Capability Atoms and Profiles
bca490b 
Fixes: #4125

Unimplemented Considerations:
1. This PR does not add support to query all capability-atom's from a command-line option. It is understood that this might be desired, due to this, the logic to generate `docs\user-guide\a3-02-reference-capability-atoms.md` was made to be "command-line friendly" so minimal changes are needed to pipe our documentation into a command-line option if this change is to be added.

Changes:
1. Added a way to document atoms inside `.capdef`. Method to document is described under `source\slang\slang-capabilities.capdef`. The goal is to error if a public atom does not have any form of documentation to ensure we always have up-to-date documentation to guide user on what an atom is/does.
    * The following `.capdef` file syntax was added
        * /// [HEADER_GROUP]
        * /// regular comment
2. When capability generator runs it auto-generates `docs\user-guide\a3-02-reference-capability-atoms.md`
3. Added to the user-guide 3 sections: `Reference`, `Reference -> Capability Profiles`, `Reference -> Capability atoms` section
@ArielG-NV ArielG-NV mentioned this issue Sep 3, 2024
Closed
@ArielG-NV ArielG-NV removed the beyond-sprint Label for issues which will be worked on but not completed during a sprint. label Sep 4, 2024
ArielG-NV added a commit to ArielG-NV/slang that referenced this issue Sep 4, 2024
@ArielG-NV
Document All Capability Atoms and Profiles
03d7e1e 
Fixes: shader-slang#4125

Unimplemented Considerations:
1. This PR does not add support to query all capability-atom's from a command-line option. It is understood that this might be desired, due to this, the logic to generate `docs\user-guide\a3-02-reference-capability-atoms.md` was made to be "command-line friendly" so minimal changes are needed to pipe our documentation into a command-line option if this change is to be added.

Changes:
1. Added a way to document atoms inside `.capdef`. Method to document is described under `source\slang\slang-capabilities.capdef`. The goal is to error if a public atom does not have any form of documentation to ensure we always have up-to-date documentation to guide user on what an atom is/does.
    * The following `.capdef` file syntax was added
        * /// [HEADER_GROUP]
        * /// regular comment
2. When capability generator runs it auto-generates `docs\user-guide\a3-02-reference-capability-atoms.md`
3. Added to the user-guide 3 sections: `Reference`, `Reference -> Capability Profiles`, `Reference -> Capability atoms` section
@ArielG-NV ArielG-NV mentioned this issue Sep 4, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ArielG-NV ArielG-NV

Labels
goal:quality & productivity Quality issues and issues that impact our productivity coding day to day inside slang kind:documentation areas where we can improve documentation in codebase
Projects
None yet
Milestone
Q3 2024 (Summer)
3 participants
@csyonghe @ArielG-NV @bmillsNV